The LionPOS API is a NestJS 11 application in apps/backend, backed by TypeORM and MySQL. It exposes REST JSON under a global /api/v1 prefix, ships OpenAPI / Swagger for contract truth, and applies Helmet, rate limiting (Throttler), ValidationPipe, and JWT + Passport guards on feature routes. This page describes how the server is put together; per-area HTTP maps live in Backend modules.
| Goals | Non-goals |
|---|
| Give engineers a single map of bootstrap, globals, and module boundaries | Replace Swagger as the field-by-field API reference |
| Explain where auth, tenancy, and POS payment hooks attach | Document every entity column (use TypeORM entities + migrations) |
| Point to tests and scripts for safe changes | Prescribe cloud infra beyond what env docs already cover |
NestFactory.create with Express adapter; applyGlobalHttpConfig sets Helmet (CSP relaxed for Swagger UI), global prefix api/v1 with Swagger UI + OpenAPI JSON paths excluded, global ValidationPipe (whitelist, forbidNonWhitelisted, transform, production-safe error messages), and Swagger setup.- CORS from
CORS_ORIGIN (comma-separated); port from PORT (default 3000).
- Optional static SPA hosting via
mountStaticSpasIfPresent (see Deployment).
| Import | Purpose |
|---|
ConfigModule | Global env (ConfigModule.forRoot({ isGlobal: true })) |
DatabaseModule | TypeORM / MySQL registration |
ThrottlerModule | Default rate limit: THROTTLE_TTL_MS / THROTTLE_LIMIT |
HealthModule | Liveness/readiness style endpoint |
AuthModule | Customer/shared auth/* routes |
VendorModule | Vendor JWT surfaces + vendor/*, auth/vendor, auth/vendor/context |
AdminModule | Admin JWT surfaces + admin/*, auth/admin |
PosModule | POS checkout + pos/payments webhooks |
Global guard: ThrottlerGuard is registered with APP_GUARD (applies before route handlers; still subject to @SkipThrottle() / Throttler config on routes).
- Validation: DTOs use class-validator + class-transformer; unknown properties are rejected when
forbidNonWhitelisted applies.
- Auth: Feature controllers use Passport JWT strategies and custom guards (e.g. admin module keys, store/tenant checks)—see Authentication.
- Tenancy: Store and vendor scoping is enforced in services (not only UI); see Tenancy — stores and outlets.
| Path | Role |
|---|
src/app.module.ts | Root composition |
src/main.ts | Process entry |
src/bootstrap-http.ts | Helmet, prefix, ValidationPipe, Swagger |
src/database/ | TypeORM module, data source, migrations path |
src/modules/*/ | Feature modules (controllers, services, DTOs, guards, strategies) |
test/ | E2E Jest config and specs |
- Request hits Express → Helmet → CORS → Throttler (if not skipped).
- Routing matches
@Controller path under /api/v1/... (unless excluded for Swagger).
- Guards run (JWT, roles, module, zone/store assertions per route).
- ValidationPipe validates/transforms the body/query DTO.
- Controller delegates to service → TypeORM / external HTTP as needed.
- Response serialized; errors mapped to HTTP exceptions (avoid leaking raw DB errors in production).
- Rate limits: tune
THROTTLE_TTL_MS and THROTTLE_LIMIT for edge/proxy environments; align with Operations if clients hit 429.
- Swagger: disable in hardened prod with
SWAGGER_ENABLED=false; JSON/UI paths stay off the versioned API prefix—see API conventions.
- Secrets: never commit
.env; index of variables in Environment.
- Payment webhooks: verify signatures and idempotency—see POS payments & webhooks.
| ID | Scenario | Expected |
|---|
| BA1 | npm run test in apps/backend | Unit tests pass |
| BA2 | npm run test:e2e | E2E suite passes against configured test env |
| BA3 | Start API + open Swagger | /docs (or SWAGGER_PATH) lists controllers |
| BA4 | Invalid DTO body | 400 with validation errors (non-prod may include messages) |
| BA5 | Throttle storm | 429 when exceeding configured limit |