ADR 0001: Modular monolith architecture
Status: Accepted
Date: 2025-10-14
Context
Wedissimo needs to support multiple business domains (Vendors, Listings, Messaging, Payments, etc.) with clear boundaries, while keeping deployment and local development simple. A traditional monolith risks turning into a "ball of mud"; microservices add significant operational overhead (multiple repos, services, deployments, and observability).
Decision
Adopt a modular monolith architecture:
- Group domain logic into modules under
/modules/*(see Module System Guide) - Treat each module as a mini-package with its own models, services, routes, tests, and docs
- Use domain concepts from the Domains documentation to define module boundaries
- Allow cross-module usage via Eloquent relationships, service contracts, and events (see Domain Communication Patterns)
This keeps everything in a single deployable application while enforcing domain boundaries through structure and conventions.
Consequences
Positive
- Simple deployment and local dev (single Laravel app, single database stack)
- Clear separation of concerns per domain, matching business language
- Easier onboarding: new developers can focus on one module/domain at a time
- Compatible with DDD concepts and future service extraction if ever needed
Negative / trade-offs
- Requires discipline to avoid "reach across" modules in ad-hoc ways
- No hard technical isolation like separate databases or services
- Shared runtime: heavy or noisy modules can affect others if not managed