065c053c16
Introduces modules/hospitality with 54 routes, BFF proxy, capability-gated nav, CRUD factory, and architecture validation docs. Co-authored-by: Cursor <cursoragent@cursor.com>
252 lines
11 KiB
Markdown
252 lines
11 KiB
Markdown
# 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 | ✅ |
|