TorbatYar/frontend/docs/frontend-architecture.md

# TorbatYar Frontend Architecture

**Version:** Phase 3 (Beauty, Healthcare, Accounting migrated)  
**Date:** 2026-07-26  
**Status:** All three business modules migrated; Accounting uses `src/modules/accounting`

---

## 1. Overview

TorbatYar SuperApp frontend is a **Next.js 15 App Router monolith** hosting the platform shell and multiple business modules. Migrated modules live under `frontend/modules/` (Beauty) and `frontend/src/modules/` (Healthcare). The shared layer is active at `frontend/src/shared/`.

```
frontend/
├── app/                 # App Router — routing files only for migrated modules
├── src/
│   ├── modules/         # Healthcare, Accounting (src-based modules)
│   └── shared/          # Cross-module UI (page states + DS re-exports)
├── modules/             # Beauty, CRM, Hospitality business packages
├── components/          # Legacy (accounting, ds, platform)
├── hooks/               # Legacy shared + deprecated shims
├── lib/                 # Legacy API clients + deprecated shims
├── shared/              # Phase 1 README scaffold (superseded by src/shared for code)
├── docs/                # Architecture & migration documentation
└── scripts/             # validate-*.mjs per module
```

---

## 2. Architectural Layers

```
┌─────────────────────────────────────────────────────────────┐
│  app/                    Routes & layouts (URL mapping)      │
└────────────────────────────┬────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────┐
│  modules/ + src/modules/ Business logic & module UI          │
│  components/{module}/    (legacy — none for migrated modules)          │
└────────────────────────────┬────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────┐
│  src/shared/             Cross-module platform layer           │
│  components/ds/          (legacy DS — re-exported via shared)│
└────────────────────────────┬────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────┐
│  lib/auth, lib/utils     Platform utilities                  │
└─────────────────────────────────────────────────────────────┘
```

### Dependency rule

**Imports flow downward only.** Shared code never imports business modules. Business modules never import sibling modules.

---

## 3. Directory Reference

### 3.1 Business module packages

| Path | Purpose |
|------|---------|
| [modules/](../modules/README.md) | Beauty, CRM, Hospitality |
| [src/modules/healthcare/](../src/modules/healthcare/) | Healthcare module |
| [src/modules/accounting/](../src/modules/accounting/) | Accounting module |

### 3.2 `src/shared/` — Active shared layer

| Directory | Purpose |
|-----------|---------|
| `src/shared/ui/` | DS re-exports + `PageLoader`, `PageError` |

### 3.3 `shared/` — Phase 1 scaffold (README only)

| Directory | Purpose | Documentation |
|-----------|---------|---------------|
| `shared/ui/` | UI atoms (Button, Input, Dialog) | [README](../shared/ui/README.md) |
| `shared/forms/` | Form fields, RHF helpers | [README](../shared/forms/README.md) |
| `shared/layouts/` | Shells, portal chrome | [README](../shared/layouts/README.md) |
| `shared/tables/` | DataTable, pagination | [README](../shared/tables/README.md) |
| `shared/charts/` | Chart wrappers | [README](../shared/charts/README.md) |
| `shared/calendar/` | Jalali date pickers | [README](../shared/calendar/README.md) |
| `shared/hooks/` | Cross-module hooks | [README](../shared/hooks/README.md) |
| `shared/utils/` | Pure utilities | [README](../shared/utils/README.md) |
| `shared/api/` | HTTP client infrastructure | [README](../shared/api/README.md) |
| `shared/theme/` | White-label theming | [README](../shared/theme/README.md) |
| `shared/providers/` | React providers | [README](../shared/providers/README.md) |
| `shared/icons/` | Icon exports | [README](../shared/icons/README.md) |
| `shared/types/` | Shared TypeScript types | [README](../shared/types/README.md) |
| `shared/constants/` | App-wide constants | [README](../shared/constants/README.md) |
| `shared/design-system/` | Tokens & patterns | [README](../shared/design-system/README.md) |

**Scaffold:** README-only subdirectories under `frontend/shared/` map to future migration targets.

### 3.4 Legacy locations

| Concern | Current path | Future path |
|---------|--------------|-------------|
| Routes | `app/{module}/` | Unchanged (may re-export from modules/) |
| Accounting UI | ~~`components/accounting/`~~ | `src/modules/accounting/` ✅ |
| Beauty UI | ~~`components/beauty/`~~ | `modules/beauty/` ✅ |
| Healthcare UI | ~~`components/healthcare/`~~ | `src/modules/healthcare/` ✅ |
| Design system | `components/ds/` | `src/shared/ui/` (re-export) |
| Hooks | `hooks/` | `shared/hooks/` + `modules/{id}/hooks/` |
| API clients | `lib/*-api.ts` | `shared/api/` + `modules/{id}/api/` |

---

## 4. Business Modules (legacy)

| Module | Route prefix | Component root | BFF |
|--------|--------------|----------------|-----|
| Platform | `/`, `/dashboard`, `/login` | `components/ui/`, root | — |
| Admin | `/admin` | `components/admin/` | — |
| Accounting | `/accounting` | `src/modules/accounting/` | `/api/accounting/*` |
| Beauty | `/beauty` | `modules/beauty/` | `/api/beauty-business/*` |
| Healthcare | `/healthcare` | `src/modules/healthcare/` | `/api/healthcare/*` |
| Hospitality | `/hospitality` | `modules/hospitality/` | `/api/hospitality/*` |

| CRM | `/crm` | `modules/crm/` | `/api/crm/*` |

Delivery: healthcare pharmacy portal only.

---

## 5. Path Aliases

Configured in `tsconfig.json`:

| Alias | Maps to | Status |
|-------|---------|--------|
| `@/*` | `./*` | Active — all existing imports |
| `@/shared/*` | `./src/shared/*` | Active — shared layer |
| `@/src/shared/*` | `./src/shared/*` | Active — explicit shared alias |
| `@/src/modules/*` | `./src/modules/*` | Active — Healthcare module |
| `@/modules/*` | `./modules/*` | Active — Beauty, CRM, Hospitality |

Healthcare uses `@/src/modules/healthcare/*` and `@/src/shared/ui`. Legacy `@/lib/healthcare-*` and `@/hooks/useHealthcare*` shims remain for backward compatibility.

---

## 6. Module Boundaries

### Allowed

```
app/beauty/         → modules/beauty/, @/components/ds or @/shared/*
app/healthcare/     → src/modules/healthcare/, @/src/shared/ui
app/accounting/     → src/modules/accounting/, @/src/shared/ui
components/ds/      → lib/utils only
src/shared/         → components/ds (re-export), no business module imports
```

### Forbidden

```
accounting  ✕  beauty | healthcare
beauty      ✕  accounting | healthcare
healthcare  ✕  accounting | beauty
ds/shared   ✕  any business module
```

Enforced by:
- `.eslintrc.json` — `no-restricted-imports` with per-module overrides
- `npm run validate:architecture` — CI-style import graph scan

Full matrix: [module-boundaries.md](./module-boundaries.md)

---

## 7. Providers & State

| Layer | Technology | Location |
|-------|------------|----------|
| Server state | TanStack Query | `components/providers/AppProviders.tsx` |
| Auth session | `useMe` hook | `hooks/useMe.ts` |
| Tenant | `useTenantId` | `hooks/useTenantId.ts` |
| Theme | CSS vars + `ThemeProvider` | `lib/theme.ts`, `styles/globals.css` |
| Color mode | Context | `components/providers/ColorModeProvider.tsx` |

Future home: `shared/providers/`, `shared/hooks/`

---

## 8. API Architecture

Browser → same-origin BFF → microservice:

```
/accounting pages  →  accountingApi  →  /api/accounting/*  →  :8002
/beauty pages      →  beautyBusinessApi  →  /api/beauty-business/*  →  :8011
/healthcare pages  →  healthcareApi  →  /api/healthcare/*  →  :8010
/admin, /dashboard →  api  →  NEXT_PUBLIC_BACKEND_URL  →  :8000
```

Future shared fetch factory: `shared/api/createApiClient.ts` (Phase 3)

---

## 9. Validation Commands

| Command | Purpose |
|---------|---------|
| `npm run build` | Production build + type check |
| `npm run typecheck` | TypeScript only (`tsc --noEmit`) |
| `npm run lint` | ESLint + Next.js rules + boundary overrides |
| `npm run validate:architecture` | Directory scaffold + import boundary scan |

| `npm run validate:healthcare` | Healthcare import, route, circular, architecture checks |
| `npm run validate:healthcare-bundle` | Post-build healthcare route segment count (requires build) |

### Healthcare migration validation (2026-07-26)

| Check | Result | Notes |
|-------|--------|-------|
| `typecheck` | ✅ Pass | |
| `lint` | ✅ Pass | 3 pre-existing accounting warnings |
| `validate:healthcare` | ✅ Pass | 114 routes, 24 module files, zero cycles |
| `validate:architecture` | ✅ Pass | |
| `build` | ⏭ Skipped | Typecheck covers compile errors; full build optional |

| `npm run validate:accounting` | Accounting import, route, circular, architecture checks |

### Accounting migration validation (2026-07-26)

| Check | Result | Notes |
|-------|--------|-------|
| `typecheck` | ✅ Pass | |
| `lint` | ✅ Pass | 3 pre-existing hook warnings in inventory/issues |
| `validate:accounting` | ✅ Pass | 120 routes, 134 module files, zero cycles |
| `build` | ⏭ Skipped | Typecheck covers compile errors |

Details: [accounting-migration-report.md](./accounting-migration-report.md)

---

## 10. Migration Phases

| Phase | Focus | Status |
|-------|-------|--------|
| 0 | Stabilize build, remove dead code | Pending |
| **1** | **Shared scaffold + boundary enforcement** | **✅ Done** |
| **2a** | **Beauty module migration** | **✅ Done** |
| **2c** | **Accounting module migration** | **✅ Done** |
| 3 | Extract portal infrastructure to `shared/layouts/` | Planned |
| 3 | Split API client monoliths | Planned |
| 4 | Extract accounting route logic | Planned |
| 5 | Middleware, error boundaries | Planned |
| 6 | New module template | Ongoing |

Details: [frontend-migration-plan.md](./frontend-migration-plan.md)

---

## 11. Related Documentation

| Document | Description |
|----------|-------------|
| [frontend-architecture-audit.md](./frontend-architecture-audit.md) | Full audit (pre-Phase 1) |
| [frontend-migration-plan.md](./frontend-migration-plan.md) | Phased roadmap |
| [module-boundaries.md](./module-boundaries.md) | Import ownership rules |
| [shared-components-report.md](./shared-components-report.md) | DS inventory |
| [dependency-report.md](./dependency-report.md) | npm & API clients |
| [import-report.md](./import-report.md) | Import patterns |
| [beauty-migration-report.md](./beauty-migration-report.md) | Beauty module migration |
| [healthcare-migration-report.md](./healthcare-migration-report.md) | Healthcare module migration |
| [accounting-migration-report.md](./accounting-migration-report.md) | Accounting module migration |

---

## 12. Phase 1 Exit Criteria

| Criterion | Status |
|-----------|--------|
| `modules/` scaffold with README | ✅ |
| `shared/*` subdirectories with README | ✅ |
| Path aliases for `@/shared/*`, `@/modules/*` | ✅ |
| ESLint cross-domain import rules | ✅ |
| Architecture validation script | ✅ |
| No business module migrations | ✅ |
| No route changes | ✅ |
| No import changes in existing code | ✅ |