2. Modular monolith
- Status: accepted, superseded in part by ADR 0029 (module manifests and the module registry)
- Date: 2026-10-29
Context and problem statement
Section titled “Context and problem statement”The system covers several business areas (parties, identity, projects, deals, invoicing, bank, reports). It must stay simple to self-host while keeping the areas independent enough to evolve separately and to support country-specific rules.
Decision drivers
Section titled “Decision drivers”- Easy self-hosting: one deployable application.
- Clear boundaries between business areas.
- Domain logic testable without a framework or a database.
- No country hard-coded in the core.
Considered options
Section titled “Considered options”- Modular monolith with enforced layer rules
- Microservices
- Unstructured monolith
Decision outcome
Section titled “Decision outcome”Chosen option: “modular monolith”, because it keeps deployment simple and still allows strict boundaries.
- PHP 8.4, Symfony 7.4 LTS and Doctrine ORM. The root namespace is
App\. - Each module lives in
src/<Module>/and is split intoDomain,ApplicationandInfrastructurelayers. Domainclasses import nothing fromSymfony\,Doctrine\or theInfrastructurelayer of other modules. The only vendor namespace allowed inDomainisDoctrine\ORM\Mapping, because entities are mapped with PHP attributes.- Raw DBAL access is not allowed in
ApplicationorDomain. - Modules communicate through their
Applicationlayer, not through each other’s internals.Infrastructureof one module is never used by another, with one exception:TenantFilterBypass, the sanctioned cross-tenant read. - The shared kernel is
Shared\Domain(money and other value types), which every module may use, and two small domain contracts that any module’sDomainmay use:Tenancy\Domain(TenantOwned,TenantId) andAudit\Domain(theAuditedmarker interface and theAuditExcludedattribute). - Besides the shared kernel, a module’s
Domainmay reference another module’sDomaintypes only where the model needs it, and each allowed direction is declared indeptrac.yaml. TodayIdentityreferencesParty(a membership links the party a user represents). Such references are entity associations to the other module’s domain types, never calls into its services. The base modulesTenancyandAuditnever depend on the modules built on them. - Money is never a
float. Amounts are stored as integer minor units plus an ISO 4217 currency code. - Every tenant-owned table has a non-null
tenant_idcolumn and an index. - Country-specific rules live in country modules (for example
src/Country/<Country>/) and are registered through interfaces. The core uses international names and never hard-codes one country. - The rules are enforced automatically in the quality gate (static analysis and architecture tests), not only by review.
Consequences
Section titled “Consequences”- Good: one deployable unit, strong boundaries, framework-free domain code.
- Good: country modules can be added without touching the core.
- Bad: boundaries need discipline and tooling to stay intact.