Assist_Design/docs/architecture/MONOREPO-ARCHITECTURE.md

Monorepo Architecture (2025)

Structure

apps/
  portal/              # Next.js frontend
  bff/                 # NestJS Backend-for-Frontend
packages/
  domain/              # Pure domain/types/utils (isomorphic)

Portal (Next.js)

src/
  app/                 # App Router routes
  components/          # Design system (ui, layout, common)
  features/            # Feature modules (auth, billing, ...)
  lib/                 # Core utils/services (api, query, env, utils, types)
  providers/           # Context providers (QueryProvider, ThemeProvider)
  styles/              # Global styles

Conventions:

• Use @/lib/* for shared frontend utilities and services.
• Avoid duplicate layers: do not reintroduce core/ or shared/ inside the app.
• Feature modules own their components/, hooks/, services/, and types/ as needed.
• Cross-feature UI belongs in components (atomic design).

BFF (NestJS)

src/
  modules/             # Feature-aligned modules (auth, orders, billing, ...)
  common/              # Nest providers/interceptors/guards
  shared/              # Backend-only shared types if any
  main.ts              # Entry point

Conventions:

• Prefer modules/* over flat directories per domain.
• Keep DTOs and validators in-module; reuse packages/domain for domain types.

packages/domain

• Domain models, status enums, validation helpers, logger, etc.
• Must be framework-agnostic (no React/Nest imports).

Path Aliases

• Portal: @/*, @/lib/*, @/features/*, @/components/*, @/providers/*.
• BFF: @/* mapped to apps/bff/src (via tsconfig/jest config).
• Domain: import via @customer-portal/domain.

Error Handling & Security

• Never leak sensitive details to end users; map errors to user-friendly messages.
• Centralize fetch/api concerns in @/lib/api/* with interceptors and strict typing.

Testing & DX (optional enhancements)

• Consider adding unit/integration tests per feature module.
• Enforce ESLint/Prettier consistent across repo.
• Optional: generators for feature scaffolding.