AI made writing the code easy. Running it in production is still hard.
This repository is the main guide: a NestJS Todo API taken from the first commit to production, covering quality gates, CI/CD, migrations, observability and rollback. It answers: how do I build and operate a production-ready API?
Part of Prod Forge — start with the organization overview: https://github.com/prod-forge
Stack
| Layer | Tools |
|---|
| Backend | NestJS · Prisma · PostgreSQL · Redis · Docker |
| Observability | Prometheus · Grafana · Loki · Promtail · Tempo |
| Quality | ESLint · Prettier · Husky · Commitlint · CI/CD |
The full stack table is on the organization page: https://github.com/prod-forge
Getting started
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 end
Grafana runs on http://localhost:3001 (admin / admin). Details:
Running the Stack Locally.
Table of contents
Conclusion
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.
What comes next
Open work is tracked in the roadmap and summarized on the organization page.
A final thought
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.
Intentionally out of scope
- 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
Contributing
We welcome any kind of contribution, please read the guidelines:
CONTRIBUTING
The MIT License
LICENSE
