project-structure-api

I kept starting new TypeScript API projects and spending the first two days doing the same setup: folder structure, error handling middleware, request validation, structured logging, JWT auth wiring, database connection pooling. None of it was interesting work — it was ceremony. I wanted a template that was actually production-ready on clone, not a tutorial scaffold that left the real work to you.

The stack is TypeScript + Express + PostgreSQL + Sequelize, with JWT authentication, OpenAPI 3.0 docs via Swagger, Jest + Supertest for tests, and Docker + GitHub Actions wired up for CI/CD. The architecture follows a clean layered pattern: Routes → Controllers → Services → Repositories → Models. Structured JSON logging in production, colorized in development. Health checks, graceful shutdown, request tracing via X-Request-Id headers, and rate limiting with Helmet security headers — all included.

Templates have a specific failure mode: they're either too opinionated (locked into one ORM, one auth approach, hard to deviate from) or too bare (a hello world with a folder structure but no real infrastructure). I tried to hit the middle ground — everything you'd need to run a real service in production, but no business logic whatsoever. The Sequelize integration, JWT middleware, and typed error hierarchy took several iterations to feel clean together. The custom error hierarchy was especially important; typed errors that flow through a consistent handler mean you never end up with 500 Internal Server Error leaking stack traces in production.

138 GitHub stars later, it's the most-starred repo in the account. Teams cloning it to start new services validated something I'd suspected: the unsexy infrastructure work has real value. Developers genuinely don't want to wire up the basics for the fifth time.