A NestJS API taken from the first commit to production, with a 16-chapter guide that explains every decision: quality gates, CI/CD, migrations, observability, fault tolerance and rollback. The domain is a Todo app on purpose, so the production practices stay visible.
- Migrations before the deploy: a one-off ECS task runs
prisma migrate deploy; the new version does not start if it fails. Release Management - Rollback in one workflow: the service switches to one of the last three task revisions. Rollback Strategy
- No dropped requests on deploy: in-flight requests are tracked and drained on
SIGTERMwhile/healthreturns503. In-Flight Requests Handling - Redis is optional: cache and rate limiting fall back instead of failing when Redis is down. Fault Tolerance
- One trace ID everywhere: the same ID in logs, Sentry events and Tempo traces. Logging & Observability
- The observability stack locally: Prometheus, Grafana, Loki and Tempo with the app, checked end to end by one script. Running the Stack Locally
- Tests on real infrastructure: 593 unit tests with coverage thresholds, and e2e tests against PostgreSQL and Redis in Testcontainers. Testing
- A committed API contract: docs/openapi.json, generated from the code.
This repository is the API. Prod Forge also has a web and mobile client and the AWS infrastructure in Terraform; the organization page has the architecture diagram and the reading order.
| Layer | Tools |
|---|---|
| Backend | NestJS · Prisma · PostgreSQL · Redis · Docker |
| Observability | Prometheus · Grafana · Loki · Promtail · Tempo |
| Quality | ESLint · Prettier · Husky · Commitlint · CI/CD |
Requires Node 24.15 or newer (CI and the image run Node 26), Docker with Compose >= 2.24 (env_file with required: false) and jq.
npm install
npm run db:generate # Prisma client (gitignored); lint, tests and start need it
docker compose up -d database cache # works without .env, using local defaults user/user/app
printf 'DATABASE_PORT=5332\nJWT_SECRET=%s\n' "$(openssl rand -hex 32)" >> .env # 5332 is the compose DB host port (.env.common says 5432); JWT_SECRET needs >= 32 chars; append, never overwrite
npm run db:migration:deploy && npm run db:seed
npm run start:dev # API on http://localhost:3000, Swagger on /docs
./scripts/verify-observability.sh # app in Docker plus Prometheus, Grafana, Loki, Tempo, checked end to endGrafana runs on http://localhost:3001 (admin / admin). Details:
Running the Stack Locally.
- 1. Repository Strategy
- 2. Architecture Decisions
- 3. Development Workflow
- 4. AI-Assisted Development
- 5. Code Quality
- 6. Documentation
- 7. Configuration Management
- 8. Database Management
- 9. Project Structure
- 10. Fault Tolerance
- 11. Error Handling
- 12. Logging & Observability
- 13. Testing
- 14. Performance
- 15. Security
- 16. Release Management
Full table of contents
- 4. AI-Assisted Development
- 12. Logging & Observability
Building software is not just about writing code.
Most engineers learn the craft of coding early in their careers. But the gap between writing working code and running a reliable system in production is wide - and rarely documented in one place.
This project is an attempt to close that gap.
Not by providing a magic template you can clone and ship. But by walking through every decision that happens before, during, and after the code is written.
The stack used here - NestJS, Postgres, Redis, Terraform, AWS - is not the point. These are just tools. The principles behind them apply to almost any production backend, regardless of language or cloud provider.
What matters is the thinking:
- Why does repository structure affect team velocity?
- Why does commit discipline make releases safer?
- Why does observability matter before something breaks?
- Why does a rollback plan need to exist before you need it?
These are not advanced topics. They are basic requirements for any system that real users depend on. The goal of Prod Forge is to make these practices visible, understandable, and reusable.
Open work is tracked in the roadmap and summarized on the organization page.
The best time to set up these practices is at the beginning of a project.
The second best time is now.
A system without observability is a system you cannot debug under pressure. A team without a defined workflow is a team that slows down as it grows. A deployment without a rollback plan is a deployment that will eventually cause an incident with no recovery path.
None of these things are difficult to set up. They are just easy to skip. This project exists as a reminder not to skip them.
- Identity provider and password management: the API verifies signed tokens and ships a login stub, see Authentication and Authorization
- Cursor pagination: list endpoints use offset pagination with
count(*), which is enough for the Todo scale, see Performance
We welcome any kind of contribution, please read the guidelines:

