# 06 — API Module Map

Stack: NestJS 10, Fastify adapter, Prisma, PostgreSQL, Redis (cache + rate limit + BullMQ), Zod (via shared `validators`), JWT.

## Modules

| Module | Responsibilities | Permissions touched |
|---|---|---|
| `AuthModule` | signup, login, OTP, refresh, logout, password reset, social | (issues tokens) |
| `UsersModule` | profile, list, update, deactivate | `profile.*.own`, `user.read.all` |
| `RolesModule` | crud roles | `role.*` |
| `PermissionsModule` | read permission catalog | `permission.read.all` |
| `BusinessesModule` | partner orgs | `business.*` |
| `MembershipsModule` | invite, accept, remove members | `membership.*` |
| `DestinationsModule` | UAE destinations | `destination.*` |
| `CategoriesModule` | category trees | `category.*` |
| `ListingsModule` | umbrella + per-kind submodules | `listing.*` |
| `RoomsModule` | hotel rooms | `room.*` |
| `BookingsModule` | reservations | `booking.*` |
| `OrdersModule` | food/pharmacy/grocery/sim orders | `order.*` |
| `PaymentsModule` | intent → confirm, webhook | `payment.*` |
| `RefundsModule` | refund flows | `refund.*` |
| `PayoutsModule` | partner payouts | `payout.*` |
| `SavedModule` | saved items | `saved.*.own` |
| `TripPlannerModule` | AI itinerary | `trip.*.own` |
| `TranslatorModule` | image OCR + translate | (rate-limited) |
| `EmergencyModule` | UAE numbers (read-only) | public |
| `ReviewsModule` | reviews + moderation | `review.*` |
| `SupportModule` | tickets, messages | `ticket.*` |
| `AuditModule` | logs (read) | `audit.read.*` |
| `I18nModule` | content translations | `content.read.public` |
| `WebhooksModule` | provider webhooks (signed) | (HMAC verified) |
| `HealthModule` | liveness/readiness | public |

## Cross-cutting

- **`RequestContextMiddleware`** populates `req.context = { userId, roles, permissions, memberships, locale, traceId }`.
- **`RbacGuard`** + `@RequirePermissions('booking.read.assigned')` decorator.
- **`PrismaScopeMiddleware`** auto-scopes queries to `own`/`assigned`.
- **`AuditInterceptor`** captures action + before/after on mutations of important resources.
- **`RateLimitMiddleware`** (Redis token bucket) per IP + per user.
- **`ProblemDetailsFilter`** emits RFC-7807 errors.
- **`ZodValidationPipe`** validates body/params against shared schemas.
- **`IdempotencyMiddleware`** for `POST /payments`, `POST /bookings`, `POST /orders`.

## OpenAPI

`@nestjs/swagger` generates `/v1/openapi.json`; published to `docs/api/openapi.json` in CI for the dashboard and mobile API client codegen.

## Folder layout

```
apps/api/src/
  main.ts
  app.module.ts
  common/                guards, interceptors, filters, decorators
  config/                env loader, schema
  prisma/                schema.prisma, seed
  modules/
    auth/
    users/
    roles/
    ...
  providers/             provider abstractions + mocks
    payment/
    map/
    sms/
    ocr/
    ai/
    translation/
    push/
    email/
    storage/
```

## Documented assumptions

1. JWT access token = 15 min, refresh = 30 days, rotated on each use, hashed at rest.
2. All write endpoints require `Idempotency-Key` for client safety on retries.
3. Provider abstractions are resolved at boot via dependency injection tokens; the active implementation is chosen by env (`PAYMENT_PROVIDER=mock|stripe|telr`).