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/	Beauty, CRM, Hospitality
src/modules/healthcare/	Healthcare module
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/forms/	Form fields, RHF helpers	README
shared/layouts/	Shells, portal chrome	README
shared/tables/	DataTable, pagination	README
shared/charts/	Chart wrappers	README
shared/calendar/	Jalali date pickers	README
shared/hooks/	Cross-module hooks	README
shared/utils/	Pure utilities	README
shared/api/	HTTP client infrastructure	README
shared/theme/	White-label theming	README
shared/providers/	React providers	README
shared/icons/	Icon exports	README
shared/types/	Shared TypeScript types	README
shared/constants/	App-wide constants	README
shared/design-system/	Tokens & patterns	README

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/*
Loyalty	/loyalty	modules/loyalty/	/api/loyalty/*
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

---

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

---

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

---

11. Related Documentation

Document	Description
frontend-architecture-audit.md	Full audit (pre-Phase 1)
frontend-migration-plan.md	Phased roadmap
module-boundaries.md	Import ownership rules
shared-components-report.md	DS inventory
dependency-report.md	npm & API clients
import-report.md	Import patterns
beauty-migration-report.md	Beauty module migration
healthcare-migration-report.md	Healthcare module migration
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	✅