AI made writing the code easy. Running it in production is still hard.

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.

The implementation is based on a simple Todo API, but the architecture follows patterns used in real production systems at scale.

Every major technical decision is documented and explained.

---

Project structure

Repository	Description
Frontend	React Web and React Mobile apps + Design System
Backend	NestJS API - the main guide
Infrastructure	Terraform on AWS

Stack

Layer	Tools
Web Client	React · Vite · Redux Toolkit · Tailwind CSS · NX
Deploy	AWS S3 · CloudFront · ECR · ECS
Backend	NestJS · Prisma · PostgreSQL · Redis · Docker
Infrastructure	AWS · RDS · ElasticCache
Observability	Prometheus · Grafana · Loki · Promtail
Quality	ESLint · Prettier · Husky · Commitlint · CI/CD

Table of contents

• 1. Repository Strategy
  • When Monorepos Work Well
  • A Real-World Problem With Monorepos
  • Why Repository Boundaries Matter

• 2. Architecture Decisions
  • Client Constraints
  • Understanding The Product
  • Technology Selection Principles
    • 1. Team Familiarity
    • 2. Community Ecosystem
    • 3. Opinionated Structure
    • 4. Stability Over Hype

• 3. Development Workflow
  • Task Management
  • Git Flow
    • Branch Naming Convention
    • Commit Conventions
  • Feature Workflow
  • Bug Fixing Workflow
  • Code Review
  • Squash Merge Strategy
  • Squash Merge Workflow
  • Why This Matters

• 4. AI-Assisted Development
  • Quality Gates First
  • Architecture Before Generation
  • Workflow
    • Input Modes
    • Plan, Then Implement
    • Save Your Prompts
  • Project Knowledge Files
    • MEMORY.md
    • REVIEW.md
    • docs/
    • Skills
  • Pre-Hooks
    • Protected Files (Edit|Write)
    • Blocked Commands (Bash)
  • Task Decomposition
  • Common AI Problems
  • Cost Optimization
  • Quality Control
    • Commit Frequently
    • Validate Edge Cases
    • Mandatory Code Review
    • Never Trust AI Blindly
  • Recommended Workflow

• 5. Code Quality
  • Layer 1. Code Formatting And Consistency
  • Layer 2. Static Analysis With ESLint
  • Layer 3. Pre-commit Protection
  • Layer 4. Commitlint Configuration
  • Layer 5. Continuous Integration Checks
  • Layer 6. Dependency Locking

• 6. Documentation
  • Recommended Documentation Structure
    • README.md
    • Swagger / OpenAPI
  • Additional Useful Documents
    • CHANGELOG.md
    • Incident Log
    • Feature Change Log
    • Roadmap

• 7. Configuration Management
  • Environment Configuration Strategy
  • Secret Management
  • Test Environment Overrides
  • NestJS Configuration Setup
  • Structured Configuration Modules
  • Accessing Configuration
  • Why This Approach Works Well

• 8. Database Management
  • Database Scripts
  • Database Manager in Docker
  • Why Not a Separate Database Service?
  • Working with Migrations
    • Running Migrations in CI/CD

• 9. Project Structure
  • API Layer
    • Thin Controllers
  • Data Validation and Sanitization
  • Unified API Responses

• 10. Fault Tolerance
  • Fault vs Failure
  • Non-Critical Dependency
    • Fallback Strategies
      • Caching Strategy
      • Throttling Strategy
  • Types of Fault Tolerance
    • High Availability
    • Graceful Degradation
  • In-Flight Requests Handling
  • Critical Dependency

• 11. Error Handling
  • Types of Errors
    • Business Logic Errors
    • Database Errors
    • Infrastructure Errors
  • Custom Errors
  • Global Exception Handling
  • User-Friendly Error Responses
  • Error Monitoring (Sentry)
    • Trace ID
    • User Context
  • Logging and Metrics

• 12. Logging & Observability
  • Application Logging
  • What Should Be Logged
  • GDPR Considerations
  • Trace ID
  • Context
  • Observability Stack
  • Logging Pipeline
  • Dashboards
  • Metrics with Prometheus
  • Why Observability Matters
  • Health Checks and Terminus
    • Critical vs Optional Dependencies
    • /health (Critical)
      • Readiness
    • /health/deps (All)
      • Optional Dependencies Handling

• 13. Testing
  • Unit Tests
    • Mocking Dependencies
  • End-to-End Tests (E2E)
    • Test Environment Setup
    • Writing Effective E2E Tests
  • Test Specs Design Style

• 14. Performance
  • Avoid Returning Unnecessary Data
  • Use Pagination for Collections
  • Use Database Indexes (When Needed)
  • Response Compression

• 15. Security
  • Request Validation
  • Response Data Sanitization
  • Security Headers
  • CORS Configuration
  • Rate Limiting
  • File Upload Security

• 16. Release Management
  • Release Strategy
  • Creating a Release
    • Release Automation
      • Versioning
        • MAJOR
        • MINOR
        • PATCH
  • Continuous Integration (CI)
    • Linting
    • Unit Tests
    • End-to-End Tests
    • Build
    • Optional Quality Gates
  • Continuous Deployment (CD)
    • Database Migration Step
      • Important Note About Migrations
    • Revision Cleanup
  • Rollback Strategy
    • Step 1 - Show Available Revisions
    • Step 2 - Rollback
  • Debugging in Production

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

This project is actively evolving. Planned additions include:

• Frontend repository with the same level of production treatment
• Mobile App repository with the same level of production treatment
• Kubernetes-based infrastructure as an alternative to ECS

If there is something missing that you would find valuable, open an issue or start a discussion.

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.

Contributing

We welcome any kind of contribution, please read the guidelines:

CONTRIBUTING

The MIT License

LICENSE