Mortezakoohjani 065c053c16 Add complete Torbat Food hospitality frontend connected to backend APIs.

Introduces modules/hospitality with 54 routes, BFF proxy, capability-gated nav, CRUD factory, and architecture validation docs.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-26 20:54:26 +03:30

11 KiB

Raw Blame History

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

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

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

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

11 KiB Raw Blame History