ADR: Three-Tier Module Architecture (Core / Custom / Marketplace)
- Status: Accepted
- Date: 2025-08-12
Context
ABI’s module system had grown organically with no enforced separation between system-level modules, private user extensions, and community-contributed integrations. All modules lived in a flat directory, making it hard to:
- Distinguish what is essential system functionality vs. optional add-ons.
- Safely enable/disable third-party marketplace modules without affecting core behavior.
- Package and distribute community modules independently from the core system.
Decision
Consolidate into a three-tier module architecture with explicit separation of concerns:
| Tier | Path | Purpose |
|---|---|---|
| Core | src/core/modules/ | Essential system functionality; always loaded |
| Custom | src/custom/modules/ | Private, project-specific extensions; not distributed |
| Marketplace | src/marketplace/modules/ | Community integrations; opt-in, disabled by default |
All three paths are registered in MODULE_PATH for auto-discovery. Marketplace modules ship with a .disabled suffix and must be explicitly enabled. The assistants/ directory is renamed to agents/ across all tiers for naming consistency.
Consequences
Positive
- Clear ownership boundaries: core is owned by the platform, custom by the project, marketplace by the community.
- Marketplace modules are safe-by-default; a broken community module cannot affect core startup.
- Enables selective activation and per-module dependency management.
Tradeoffs
- Three
MODULE_PATHentries increase discovery scan time proportionally. - The
.disabledsuffix convention is non-standard; developers must remember to rename files to activate modules. - Boundary enforcement is by convention, not by code — nothing prevents core code from importing marketplace code directly.