# Code Architecture Map

This page is the fast handover map for engineers taking over the codebase.

## Repository Structure

- `apps/admin`:
  Next.js admin panel. Owns auth UI, CMS management screens, and protected workflows.
- `apps/web`:
  Next.js public site. Renders CMS-managed content and public-facing routes.
- `packages/db`:
  Prisma schema, generated client usage, and data access services.
- `packages/content`:
  Domain-level Zod schemas and shared contracts.
- `packages/crud`:
  Shared CRUD service pattern (validation, not-found behavior, audit hook contracts).
- `packages/ui`:
  Shared UI primitives used by admin/public apps.
- `packages/i18n`:
  Shared locale helpers.

## Runtime Boundaries

- Admin app:
  writes content and settings, enforces RBAC, runs Better Auth route handlers.
- Public app:
  reads published content and settings; no public auth coupling.
- DB package:
  only data access and business-persistence rules.
- Content package:
  only validation and domain typing; no DB or framework runtime coupling.

## Core Feature Modules

- Auth and user guards:
  `apps/admin/src/lib/auth/server.ts`, `apps/admin/src/app/api/auth/[...all]/route.ts`
- Access and route permissions:
  `apps/admin/src/lib/access.ts`, `apps/admin/src/lib/route-guards.ts`
- Media domain + storage:
  `packages/db/src/media-foundation.ts`, `apps/admin/src/lib/media/storage.ts`
- Pages and navigation:
  `packages/db/src/pages-navigation.ts`, `apps/admin/src/app/pages/*`, `apps/admin/src/app/navigation/*`
- Commissions and customers:
  `packages/db/src/commissions.ts`, `apps/admin/src/app/commissions/page.tsx`
- Announcements and news:
  `packages/db/src/announcements.ts`, `apps/admin/src/app/announcements/page.tsx`, `apps/admin/src/app/news/page.tsx`

## Extension Rules

- Add/adjust schema first in `packages/content`.
- Implement persistence in `packages/db`.
- Wire usage in app route/actions after schema/service are in place.
- Add tests at service and app-boundary levels before marking TODO items done.