apiVersion: jdai.upss/v1
kind: Adr
id: adr.modular-monolith-architecture
version: 1
status: draft
metadata:
owners:
- JerrettDavis
reviewers:
- upss-adr-curator
lastReviewed: 2026-03-07
changeReason: Establish the first canonical ADR for the modular monolith architecture decision.
date: 2026-03-07
context: The system needs a well-defined architecture style that balances modularity, team autonomy, and operational simplicity during early product stages while preserving the ability to extract services later.
decision: Adopt a modular monolith architecture where each bounded context is isolated by project boundaries and communicates through explicit public APIs, while sharing a single deployment unit.
alternatives:
- title: Microservices from the start
description: Decompose the system into independently deployable services from day one.
pros:
- Independent scaling per service.
- Strong module isolation enforced by network boundaries.
cons:
- High operational overhead for a small team.
- Distributed system complexity introduced before domain boundaries are stable.
- title: Traditional layered monolith
description: Organize code by technical layer (controllers, services, repositories) without module boundaries.
pros:
- Simple initial setup and familiar to most developers.
- Single deployment unit reduces operational burden.
cons:
- Cross-cutting dependencies accumulate quickly.
- Difficult to extract services later without significant refactoring.
consequences:
- All bounded contexts must communicate through well-defined public APIs rather than direct internal references.
- Future service extraction requires only replacing in-process calls with network calls at module boundaries.
- The team must enforce module boundaries through code review and automated validation until physical separation is warranted.
supersedes: []
conflictsWith: []
trace:
upstream:
- specs/vision/examples/vision.example.yaml
downstream:
implementation:
- src/JD.AI.Core/Specifications/AdrSpecification.cs
governance:
- tests/JD.AI.Tests/Specifications/AdrSpecificationRepositoryTests.cs