2. Prefer a modular monolith before microservices
Date: 2026-05-03
Status
Accepted
Context
We need a default approach for structuring applications as the monorepo grows. Microservices add network, deployment, and operational overhead that is often unnecessary early in a product’s life.
Decision
Start new systems as a modular monolith: clear module boundaries and contracts inside one deployable. Extract services only when we have concrete drivers—scaling limits, independent deployment needs, or team ownership boundaries—not ahead of need.
Consequences
- Positive: Simpler operations, easier debugging, fewer cross-service failures during iteration.
- Positive: AI-assisted refactors stay within one codebase boundary until extraction is justified.
- Tradeoff: We must enforce module boundaries through discipline and reviews; we will revisit extraction when metrics or org structure demand it.