# ADR 011: Modular Monolith First **Status**: Accepted **Date**: 2026-04-19 **Deciders**: Architecture Lead --- ## Context KADi's BMW readiness work tempts two over-corrections: (a) splitting into microservices to "look enterprise-ready", or (b) introducing a new framework (NestJS, NX, Apollo/GraphQL) on the assumption that BMW will mandate it. Both would multiply complexity without solving the actual portability and governance problems. ## Decision Stay on a single Next.js (App Router) modular monolith. Enforce module boundaries via tsconfig paths, ESLint boundaries (ADR 015), and public-entrypoint discipline. Do not extract services until a measured constraint (scaling, deployment cadence, ownership boundary) makes it cheaper to split than to keep together. ## Rules this decision creates 1. New work belongs to a clearly named module under `lib//`, `components//`, or `app//`. No new top-level "misc" buckets. 2. Modules expose a public entrypoint (`index.ts`); deep imports across modules are discouraged and will be flagged in Phase 2 once boundaries are at error level. 3. Cross-module communication uses typed function calls, repositories, or events — never imports from a module's `internal/` directories. 4. The product runs as a single deployable; horizontal split is a future ADR, not an implicit assumption. 5. Background work uses the existing dispatcher abstraction (see ADR 005); no new long-running orchestration framework introduced in this phase. ## Consequences ### Forbidden - Introducing GraphQL, NestJS, NX, or any monorepo orchestrator without an ADR. - Spinning out a microservice for a feature that has not exhausted the in-monolith boundary path. - Re-platforming "in passing" inside an unrelated PR. ### Accepted - Modules grow inside one process until proven that splitting is cheaper than keeping. - Some duplicated wiring code between modules (acceptable in exchange for keeping deploy unit count = 1). ## Related - ADR 010 — Product core vs customer adapter - ADR 014 — Shared platform services strategy - ADR 015 — Architecture boundary enforcement - ADR 019 — New module golden path