68 lines
2.0 KiB
Markdown
68 lines
2.0 KiB
Markdown
|
## 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.
|
||
|
|
|
||
|
|
|