Documentation
Disclaimer
The documentation in this directory was written with the assistance of GitHub Copilot (powered by Claude Sonnet 4.6).
Every document has been manually reviewed and verified against the actual implementation to ensure accuracy and correctness. If you find any discrepancies, please open an issue or submit a pull request.
Standards & References
This project follows established industry standards and methodologies. The sections below document the specific specs, RFCs, and practices this codebase is built against.
Twelve-Factor App
This project aligns with the Twelve-Factor App methodology — a set of best practices for building modern, scalable, maintainable server-side applications.
| Factor | How it applies |
|---|---|
| Codebase | Single repo, one codebase tracked in Git, multiple deploys via env |
| Dependencies | All dependencies declared in package.json, enforced with PNPM lockfile |
| Config | All configuration via environment variables, validated at startup via AppEnvDto |
| Backing Services | MongoDB, Redis, AWS S3/SES, Firebase — treated as attached resources via env config |
| Build, Release, Run | Build (pnpm build) is strictly separated from runtime |
| Processes | Stateless app processes — session and cache state stored in Redis, not in-memory |
| Port Binding | App self-contained via NestJS HTTP server, port exposed via APP_PORT env |
| Concurrency | Horizontal scaling supported — stateless processes, shared Redis for sessions |
| Disposability | Fast startup, graceful shutdown — no sticky sessions or local state |
| Dev/Prod Parity | Same stack (Docker Compose) for local dev and production |
| Logs | Logs as event streams via Pino to stdout — no log file management in app |
| Admin Processes | One-off tasks via dedicated migration and seed scripts (pnpm migration:seed) |
Security Standards
| Concern | Standard |
|---|---|
| JWT Access Token | ES256 — ECDSA + SHA-256 (RFC 7518 , RFC 7519 ) |
| JWT Refresh Token | ES512 — ECDSA + SHA-512 (RFC 7518 , RFC 7519 ) |
| Two-Factor Auth | TOTP — SHA-1, 6 digits, 30s period (RFC 6238 ) |
| Password Hashing | bcrypt — 8 salt rounds |
| Encryption at Rest | AES-256-CBC (2FA secrets), AES-CBC + PKCS7 (general data) |
| HTTP Security Headers | Helmet v8 — CSP, Strict-Transport-Security, X-Frame-Options, etc. |
| CORS | Configurable allowlist with wildcard subdomain support, preflight max-age 24h |
| Rate Limiting | 10 requests / 500ms window — global guard via @nestjs/throttler |
| Authorization | CASL — fine-grained ability-based access control (subject + action) |
| API Key Auth | Machine-to-machine via x-api-key header |
| Sensitive Data | Auto-redacted in logs (password, token, apiKey) via Pino serializers |
| Threat Coverage | OWASP Top 10 — input validation, injection prevention, auth hardening |
Table of Contents
Getting Started
Start here to get the project running and understand its foundations.
- Installation — Set up the development environment step by step
- Environment — Configure all environment variables via
.env - Configuration — Understand the Config Module and per-concern config files
- Project Structure — Learn the modular architecture and repository design pattern
Core
Essential systems that power every feature in the project.
- Database — Prisma + MongoDB replica set, transactions, and the Database Module
- Authentication — JWT (ES256/ES512), session lifecycle, API key auth
- Authorization —
UserProtected,RoleProtected,PolicyAbilityProtected,TermPolicyAcceptanceProtected - Device — Device fingerprinting,
DeviceOwnership, max 1 session per device - Response — Standardized response decorators, pagination response, file download
- Request Validation —
ValidationPipe,class-validator, body/query/path validation - Handling Error — Exception filters, standardized HTTP error responses, i18n errors
- Message — i18n with
nestjs-i18n, nested JSON message files insrc/languages/ - Cache — Redis caching with shared
RedisCacheModule, TTL strategy - Queue — BullMQ background jobs,
QueueProcessorBase, retry/backoff - Logger — Pino logging, file rotation, sensitive data redaction, Sentry integration
- Security and Middleware — HTTP middleware layer, headers, rate limiting
Advanced
Additional features and integrations for production-grade deployments.
- Pagination — Offset-based, cursor-based pagination, advanced filtering
- Notification — Multi-channel notifications (email, push, inApp, silent) via BullMQ
- Two Factor — TOTP 2FA with authenticator apps and backup codes
- Feature Flag — Dynamic feature management, gradual rollouts, A/B testing
- Activity Log — Recording successful user activities with
@ActivityLog - Term Policy — Legal agreements, versioning, and user consent enforcement
- File Upload — Single/multiple file uploads, CSV processing, upload decorators
- Presign — AWS S3 presigned URLs for secure time-limited object access
- Third Party Integration — AWS S3/SES, Firebase, Sentry, no-op mode
- Doc — Swagger/OpenAPI decorators via the Doc Module
- Analytics — Planned analytics design using MongoDB aggregation pipelines
Last updated on