Skip to content
prod-forgePublic

About

Prod Forge is an open-source reference that shows how to build and operate a production-ready system: AI-assisted development, quality gates, CI/CD, infrastructure, observability, migrations, and rollback.

Topics

Resources

Code of conduct

Contributing

Stars

500 stars

Watchers

3 watching

Forks

Latest commit

 

History

226 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Prod Forge

License: MIT Release CI

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.

What's inside

  • 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 SIGTERM while /health returns 503. 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.

Grafana dashboard of the API

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.

Stack

Layer Tools
Backend NestJS · Prisma · PostgreSQL · Redis · Docker
Observability Prometheus · Grafana · Loki · Promtail · Tempo
Quality ESLint · Prettier · Husky · Commitlint · CI/CD

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

Full 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

About

Prod Forge is an open-source reference that shows how to build and operate a production-ready system: AI-assisted development, quality gates, CI/CD, infrastructure, observability, migrations, and rollback.

Topics

Resources

Code of conduct

Contributing

Stars

500 stars

Watchers

3 watching

Forks

Releases

Contributors

Languages