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