Diagrams
Visual reference for how Apso fits together. Rendered in-repo with Mermaid (no external tooling). Each diagram reflects the current code.
Platform architecture
How the pieces interact: the client talks to the platform server for everything CRUD/billing/auth, and to the build engine to provision a deployed service; the SDK consumes the deployed service directly.
Legend: solid arrows are request/provision paths; dashed arrows are real-time status (Pusher). The deployed service is what your users’ traffic and the SDK hit; the platform server is the control plane.
Deploy flow
A deploy runs as a Step Functions saga (provisioner-v2). Steps run in order; any failure routes to cleanup/rollback rather than leaving a half-provisioned service. Progress is streamed to the client over Pusher.
Legend: the happy path is top-to-bottom; every step has a failure edge into a single cleanup path (the saga’s compensation). A tier upgrade reuses the same pattern on a separate state machine to resize Lambda, API Gateway, and Neon.
Domain events (transactional outbox)
Services opt entities in to events via the CLI-emitted manifest (EVENT_EMITTING_ENTITIES). The @apso/domain-events engine captures changes in the same database transaction as the write (a transactional outbox), then relays them to delivery destinations — so an event is never emitted for a change that rolled back, and never lost for one that committed.
Legend: the write and the outbox insert share one transaction (left edge); the relay is asynchronous (it reads committed outbox rows and delivers). The engine ships as a versioned library, wired per service — the CLI only emits the manifest of participating entities.
CRUD request path
A request to a generated service API flows through the Lambda, guards, and the CRUD request parser before hitting Postgres, and comes back as a paginated envelope.
Legend: guards run before any query, so an unauthorized or out-of-scope request never reaches the database. The parser turns the filter[n]/sort[n]/join[n]/limit/page query string into the SQL query — see the API Reference.
Screenshots requested in the tracking issue are not included here — capturing and annotating live UI is out of scope for an in-repo, tooling-free contribution. These diagrams cover the architecture, sequence, and data-flow items; UI screenshots are a separate follow-up.