# TorbatYar Frontend Architecture

**Version:** Phase 1 (shared scaffold)  
**Date:** 2026-07-26  
**Status:** Architecture created — business modules not migrated

---

## 1. Overview

TorbatYar SuperApp frontend is a **Next.js 15 App Router monolith** hosting the platform shell and multiple business modules (Accounting, Beauty, Healthcare, Platform Admin). Phase 1 introduces a **formal shared architecture** under `frontend/shared/` and a **future module home** under `frontend/modules/` without moving existing code or changing routes/imports.

```
frontend/
├── app/                 # App Router (unchanged — 350 routes)
├── components/          # Legacy components (unchanged)
├── hooks/               # Legacy hooks (unchanged)
├── lib/                 # Legacy API clients & utilities (unchanged)
├── modules/             # 🆕 Future business module packages (scaffold)
├── shared/              # 🆕 Platform layer (scaffold)
├── docs/                # Architecture & audit documentation
└── scripts/             # validate-architecture.mjs, generators
```

---

## 2. Architectural Layers

```
┌─────────────────────────────────────────────────────────────┐
│  app/                    Routes & layouts (URL mapping)      │
└────────────────────────────┬────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────┐
│  modules/ (future)       Business logic & module UI          │
│  components/{module}/    (legacy — current location)         │
└────────────────────────────┬────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────┐
│  shared/                 Cross-module platform layer         │
│  components/ds/          (legacy DS — current location)      │
└────────────────────────────┬────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────┐
│  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 `modules/` — Business module packages

| Path | Purpose |
|------|---------|
| [modules/](../modules/README.md) | Future home for self-contained business modules |

**Phase 1:** README only. Accounting, Beauty, Healthcare migrated; **CRM** active under `modules/crm/`.

### 3.2 `shared/` — Platform layer

| 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) |

**Phase 1:** Each subdirectory contains a README mapping to legacy source locations. No code migrated.

### 3.3 Legacy locations (unchanged)

| Concern | Current path | Future path |
|---------|--------------|-------------|
| Routes | `app/{module}/` | Unchanged (may re-export from modules/) |
| Accounting UI | `components/accounting/` | `modules/accounting/components/` |
| Beauty UI | `components/beauty/` | `modules/beauty/components/` |
| Healthcare UI | `components/healthcare/` | `modules/healthcare/components/` |
| Design system | `components/ds/` | `shared/ui/` + `shared/design-system/` |
| 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` | `components/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/*` | `./shared/*` | Active — for future migration |
| `@/modules/*` | `./modules/*` | Active — for future modules |

**Phase 1 does not change existing imports.** Legacy `@/components/ds` remains canonical until Phase 2 migration.

---

## 6. Module Boundaries

### Allowed

```
app/accounting/     → components/accounting/, components/ds/, hooks/, lib/accounting-api
app/beauty/         → components/beauty/, components/ds/, hooks/, lib/beauty-business-api
app/healthcare/     → components/healthcare/, components/ds/, hooks/, lib/healthcare-api
components/ds/      → lib/utils only
shared/ (future)    → other shared/*, lib/auth, lib/utils
```

### 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 |

### Phase 1 validation results (2026-07-26)

| Check | Result | Notes |
|-------|--------|-------|
| `validate:architecture` | ✅ Pass | Scaffold complete; zero cross-domain imports |
| `lint` | ✅ Pass | 3 warnings in `inventory/issues/page.tsx` (pre-existing) |
| `typecheck` | ❌ Fail | Pre-existing: `Button` `loading` prop in `purchase/returns/page.tsx` (Phase 0) |
| `build` | ❌ Fail | Same TypeScript error as typecheck |

---

## 10. Migration Phases

| Phase | Focus | Status |
|-------|-------|--------|
| 0 | Stabilize build, remove dead code | Pending |
| **1** | **Shared scaffold + boundary enforcement** | **✅ Current** |
| 2 | 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 |
| [refactor-risk-analysis.md](./refactor-risk-analysis.md) | Refactor risks |

---

## 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 | ✅ |