Architecture
The current Lenso runtime shape and ownership boundaries.
Lenso starts as one deployable backend. That keeps first-user setup boring while still forcing modules to declare the boundaries they would need if they later move out of process.
For the higher-level model, read Platform Concepts. For generated artifacts and architecture gates, read Contracts and Checks.
Runtime shape
A generated host contains:
- API app for HTTP routes and admin APIs
- worker app for background processing and runtime functions
- migration app for deterministic database setup
- Postgres for host-owned persistence
- optional Redis for auth session lookup
- bundled Runtime Console served by the API
This is a modular monolith first. A Module is Linked into a Host. Code that needs its own process, runtime, Store, or deployment cadence is a Service that can provide Modules through explicit provider contracts.
Repository ownership
| Repository | Owns |
|---|---|
lenso |
Rust services, platform crates, first-party modules, migrations, contracts |
lenso-console |
Independent Console Service, Shell, and Console package APIs |
lenso-cli |
lenso command, host starter template, local service wrapper |
lenso-examples |
Runnable module examples and smoke checks |
Package rule
The public surface should stay small. Publish packages and commands only when they have a clear target author, a minimal install command, a stable import path or binary name, and README usage that starts from a blank project.
Linked Module or Service
Use a Linked Module when the capability belongs to the Host and its release cycle. Use a Service when code needs a different runtime, owner, deployment cadence, Store, or trust boundary.
The Service owns its process and terminal operational evidence. The Host owns its Module composition, capability checks, and Data Plane. Lenso Console observes and coordinates through the System Plane without taking effect authority away from either side.
Split later
Keep a Module Linked in the Host until there is a concrete reason to split it: different runtime, separate ownership, independent release cadence, or a trust boundary. When that reason exists, extract an independently running Service and install its declared provider contract. Remote Module is not a current loading source or public package category.