fix production issues

docs/project-design/FEATURES.md

@@ -35,6 +35,7 @@ There is no separate frontend app for a white-label company public site in this
 
 - Company-scoped vehicles, customers, reservations, offers, payments, complaints, and notifications
 - API tenant isolation through employee auth plus `companyId` scoping
+- Cross-tenant negative regression suite (`cross-tenant-isolation` integration tests)
 - Company profile, brand, contract settings, insurance policies, pricing rules, and accounting settings
 - Public API key generation/regeneration for company integrations
 
@@ -76,10 +77,12 @@ There is no separate frontend app for a white-label company public site in this
 
 - SaaS trial and subscription lifecycle
 - Subscription status handling including `TRIALING`, `ACTIVE`, `PAYMENT_PENDING`, `PAST_DUE`, `SUSPENDED`, `CANCELLED`, `EXPIRED`, `PAUSED`, `UNPAID`
-- Plan pricing loaded from DB or fallback config
+- Plan pricing and entitlements from a single catalog (`packages/types` `planCatalog`) with DB overrides where configured
+- Homepage marketing prices derived from the same catalog
 - AmanPay and PayPal provider support for SaaS subscription checkout
 - Subscription invoice history
 - Platform billing accounts, billing invoices, billing events, refunds, credit notes, and tax records
+- Canonical billing models preferred over legacy subscription-invoice-only writes (see `docs/BILLING_NOTIFICATION_SOURCE_OF_TRUTH.md`)
 
 ### Rental payments
 
@@ -97,6 +100,16 @@ There is no separate frontend app for a white-label company public site in this
 - In-app notifications
 - Notification templates and per-channel preferences
 - Notification history for company users
+- Durable notification outbox with leased dispatch on `api-worker` (Redis publish for IN_APP)
+- Canonical event/recipient/delivery models preferred over legacy flat notifications
+
+### Ops and production-readiness baselines
+
+- `GET /ready` and `GET /metrics` on the API
+- Shared Redis rate limiting and Carplace idempotency
+- Optional S3/MinIO file storage driver
+- OpenAPI coverage CI gate
+- Design summary: `docs/design/`
 
 ### Reservation-adjacent advanced operations
 
@@ -112,6 +125,7 @@ There is no separate frontend app for a white-label company public site in this
 ### Admin app
 
 - Admin login and password reset
+- Admin 2FA enrollment; fresh 2FA required for money / high-privilege mutations (TTL)
 - Admin dashboard
 - Company management
 - Renter management
@@ -121,6 +135,7 @@ There is no separate frontend app for a white-label company public site in this
 - Pricing configuration and promotions
 - Notification review
 - Carplace/site config management
+- Per-tenant Docker/container orchestration UI is **out of scope** (ADR-001)
 
 ## Present But Not Active Product Features
 
@@ -135,6 +150,8 @@ These exist partially in code or schema, but they are not active end-user produc
 - Admin impersonation through Clerk sessions
 - Multi-currency SaaS checkout beyond `MAD`
 - Separate white-label company-site frontend app
+- Per-tenant Docker container orchestration (explicitly disabled — ADR-001)
+- Microservice extraction of payments/webhooks/media (deferred — ADR-003)
 
 ## Explicitly Out Of Scope For Current Docs
 

docs/project-design/api-routes.md

@@ -13,19 +13,24 @@ Source of truth for the runtime wiring:
 
 The API is an Express application mounted under `/api/v1` with a few non-versioned utility endpoints:
 
-- `GET /health` returns process health.
+- `GET /health` returns process liveness.
+- `GET /ready` returns readiness (PostgreSQL, Redis, storage). Returns `503` when a dependency fails.
+- `GET /metrics` returns Prometheus-style ops metrics (request counts/latency, outbox gauges).
 - `GET /docs` serves Swagger UI.
 - `GET /api/v1/openapi.json` returns the generated OpenAPI document.
 - `/storage/*` serves uploaded assets such as logos, hero images, vehicle photos, and reservation/customer documents.
 
+A dedicated **`api-worker`** process runs notification outbox dispatch and scheduled jobs (Phase 1). The API process must not embed those jobs when multiple replicas are used (`ENABLE_EMBEDDED_JOBS` stays false). See `docs/design/RUNTIME_AND_OPS_SURFACE.md`.
+
 The app boot sequence in `apps/api/src/app.ts` is intentionally ordered:
 
 1. CORS is applied first.
 2. storage guards are applied before static serving so private customer license files are never anonymously retrievable.
 3. Swagger UI is mounted before Helmet so the UI assets are not blocked by CSP.
 4. webhook routes that require raw payload handling are mounted before `express.json()`.
-5. Helmet, request logging, JSON parsing, and the module routers are mounted.
+5. Helmet, request logging (structured JSON), metrics middleware, JSON parsing, and the module routers are mounted.
 6. the centralized error middleware converts validation, Prisma, and application errors into consistent JSON responses.
+7. Spoofable forwarded headers are scrubbed unless `TRUSTED_FORWARD_HEADERS=true` (see `docs/ops/proxy-trust.md`).
 
 ## Request Lifecycle
 
@@ -382,6 +387,8 @@ Successful route handlers usually return:
 Common deviations:
 
 - `/health`
+- `/ready`
+- `/metrics`
 - `/api/v1/docs`
 - webhook receipt payloads
 - file downloads such as admin invoice PDFs
@@ -393,4 +400,6 @@ There are two documentation layers in the codebase:
 1. runtime API docs from Swagger/OpenAPI at `/docs` and `/api/v1/openapi.json`
 2. this markdown document, which explains design decisions, route grouping, and request flow
 
-The OpenAPI file is useful for request/response contracts, but it is not yet a perfect mirror of every newer route. This document should be updated together with `app.ts`, route files, and the OpenAPI generator whenever route groups change.
+Production-readiness design updates (Phases 0–4) are summarized under `docs/design/`.
+
+The OpenAPI file is useful for request/response contracts. CI enforces a minimum coverage gate via `npm run openapi:coverage`. This document should be updated together with `app.ts`, route files, and the OpenAPI generator whenever route groups change.