# `apps/api-nest` — Secondary backend (NestJS 11)

Runs alongside the .NET 9 primary API. Use as:

- **Queue worker host** — Phase 6 wires BullMQ processors here.
- **WebSocket gateway** — realtime channels share the auth contract with the .NET API.
- **BFF** — when frontend needs aggregation across services and the .NET API isn't the right place.

## Run

```bash
cp .env.example .env       # then edit JWT_ACCESS_SECRET / JWT_REFRESH_SECRET to 32+ chars
docker compose up -d
pnpm --filter @loma-portal/api-nest dev
# → http://localhost:3001
# → Swagger at http://localhost:3001/docs
```

## Layout

```
src/
├── main.ts                                Bootstrap: pino logger, global pipe/filter/interceptor, Swagger
├── app.module.ts                          ConfigModule (Zod-validated env) + ThrottlerModule + LoggerModule + feature modules
├── common/
│   ├── config/env.schema.ts               Zod schema for env validation
│   ├── decorators/
│   │   ├── current-user.decorator.ts
│   │   └── permissions.decorator.ts       @Permissions('users.read', ...)
│   ├── dto/api-response.dto.ts            ApiResponse<T> + paged() helper
│   ├── filters/all-exceptions.filter.ts   RFC 7807 ProblemDetails
│   ├── guards/permissions.guard.ts
│   └── interceptors/
│       ├── correlation-id.interceptor.ts
│       └── transform.interceptor.ts       Wraps responses in ApiResponse<T> envelope
└── modules/
    ├── auth/                              login + refresh (currently proxies to .NET API — see auth.service.ts)
    ├── user/                              users list (Prisma wired in Phase 5)
    ├── role/                              roles list (Prisma wired in Phase 5)
    ├── audit/                             AuditService.emit(event) — queue worker writes in Phase 6
    ├── health/                            @nestjs/terminus health checks
    └── prisma/                            PrismaService stub (real PrismaClient lands Phase 5)
```

## Why a second backend?

The .NET API owns the canonical data model and synchronous request/response API. NestJS handles workloads where Node.js is a better fit:

- BullMQ + ioredis for queue-driven work (audit shipping, notifications, scheduled exports).
- WebSocket gateways with first-class TypeScript types from `packages/api-contracts/`.
- Edge-friendly BFFs where the front door benefits from JS server-rendering.
