Docs/Architecture
Architecture
How apps, capabilities, and providers fit together.
Boson keeps application logic independent of cloud vendors. Capabilities talk to the kernel, ports, and events; adapters wrap provider SDKs at the edge.
Dependency direction
generated app → boson-runtime → core capabilities
generated capability → boson-sdk → capability / ports / events / db helpers
apps → adapters → vendor SDKs
dashboard / CLI → Admin API → server → providers
Provider SDK types must not appear in capabilities or public contracts.
Standalone apps depend on boson-runtime and boson-sdk rather than forking
the platform repository.
Layers
| Layer | Responsibility |
|---|---|
| Apps | HTTP host, worker, dashboard, CLI, website |
| Runtime / SDK | Shared composition and public extension facade |
| Capabilities | Identity, orgs, files, jobs, audit, notifications |
| Kernel / ports / events | Config, contracts, versioned envelopes |
| Adapters | Storage, queue, mailer, and other providers |
Architectural locks
- PostgreSQL is the system of record.
- Server and Worker never depend on Dashboard, CLI, or the website.
- Dashboard uses APIs; the CLI delegates local lifecycle work to the private orchestration layer rather than exposing service or migration internals.
- Admin and application authorization remain separate.
- Capabilities own their schema and do not query another capability's tables.
- Side effects use versioned events and a transactional outbox.
- Provider implementations remain behind small ports.
- Deployment packaging never leaks into application logic.