⚙️ Backend Architecture

Structuring backend applications for reliability and scalability.

Project structure

src/
├── modules/
│   ├── auth/
│   │   ├── auth.controller.ts
│   │   ├── auth.service.ts
│   │   ├── auth.repository.ts
│   │   └── auth.types.ts
│   ├── users/
│   └── orders/
├── shared/
│   ├── middleware/
│   ├── errors/
│   ├── utils/
│   └── types/
├── config/
│   ├── database.ts
│   ├── env.ts
│   └── logger.ts
└── server.ts

Layer responsibilities

Layer	Does	Doesn't
Controller	Parse request, validate input, return response	Business logic, DB queries
Service	Business logic, orchestration	HTTP concerns, direct DB access
Repository	Data access, queries	Business logic, HTTP

Authentication patterns

Pattern	Best for
JWT (stateless)	APIs, mobile apps, microservices
Session (stateful)	Traditional web apps, SSR
OAuth2 / OIDC	Third-party login, SSO
API keys	Service-to-service, public APIs

Middleware pipeline

Request → Rate Limit → Auth → Validation → Handler → Error Handler → Response

Logging

• Use structured logging (JSON)
• Include request ID for tracing
• Log levels: error, warn, info, debug
• Log at boundaries: incoming request, outgoing response, external calls
• Never log sensitive data (passwords, tokens, PII)

Health checks

GET /health         → 200 { status: 'ok' }
GET /health/ready   → 200 { db: 'ok', cache: 'ok', queue: 'ok' }

Graceful shutdown

1. Stop accepting new requests
2. Finish in-flight requests (with timeout)
3. Close database connections
4. Close message queue connections
5. Exit process