Skip to Content
Apso is in public beta. Get started
ArchitectureDiagrams

System diagrams

Use these diagrams to understand which Apso component owns each part of the build and runtime path. Each view names the boundary first, then shows the implementation details you can inspect.

Control plane and generated runtime

The Apso app and platform API manage workspaces, service definitions, identity, billing, and build requests. The build engine creates the service. After deployment, client and SDK traffic goes to the generated service instead of passing through the platform API.

Platform topologyThe control plane builds the service. Product traffic goes to the service.
Separated runtime
Product workspace

Developer + Apso app

Workspaces and servicesSchema and credentialsBilling and identity
Platform API
Build control plane

Build engine + CLI

Validate the contractGenerate the codebaseProvision infrastructure
Step Functions + Lambda
Generated runtime

Owned service

API Gateway + applicationPostgreSQL databaseSDK and REST clients
Your product traffic
Build status returns to the Apso app. Runtime requests do not pass through the platform API.
BoundaryResponsibility
Apso app and platform APIConfigure the service, schema, environment, identity, and billing
Build engine and CLIValidate, generate, provision, and report build status
Generated serviceHandle product traffic, authorization, application logic, and persistence

Deployment workflow

Provisioning advances through an ordered workflow. Each step reports status to the dashboard. A failure routes through cleanup so the platform does not present an incomplete service as ready.

Provisioning workflowAn ordered build with one cleanup path.
Progress events
  1. 01InitializeValidate the project and prepare secure repository access.
  2. 02DatabaseProvision the database and connection configuration.
  3. 03ServiceDeploy the generated application and API boundary.
  4. 04CompletePublish the live endpoint and final build status.
Any failed stepCleanup and rollbackReturn a failed build status without leaving an incomplete service.
The build engine streams state changes back to the dashboard while the workflow advances.

A tier change uses the same ordered pattern with the capacity settings required by the selected service plan.

Transactional domain events

Entities can opt into domain events through the generated service manifest. The service records the entity change and its event in one database transaction. A relay reads committed outbox rows and delivers them to the configured destination.

Domain event pathCommit the data and event together, then deliver asynchronously.
Transactional outbox
Same database transaction
  1. 01Service writeEntity change
  2. 02SubscriberCapture change
  3. 03MapperBuild event
  4. 04OutboxCommit record
  5. 05RelayRead committed
  6. 06DestinationDeliver event
The relay sees only committed outbox rows, so rolled-back writes do not emit product events.

This pattern protects both sides of the contract: a rolled-back write produces no event, and a committed event remains available for retry if delivery fails.

Generated API request

Authentication and tenant scope run before the generated handler reaches the data layer. The CRUD request parser translates filters, sorting, joins, limits, and pagination into the framework query.

Request lifecycleOne request, with every backend boundary visible.
Authenticated
  1. 01ClientServer component, mobile app, or service
  2. 02SDK or RESTTyped operation and validated payload
  3. 03IdentitySession, JWT, or API key context
  4. 04Tenant scopeAuthorization and row boundary
  5. 05ServiceGenerated route, product logic, and database
Keep privileged credentials on the server and pass only verified identity and tenant context into the generated service.
StageImplementation detail
EdgeAPI Gateway or the selected HTTP runtime receives the request
IdentitySession, JWT, or API key produces the normalized auth context
ScopeGenerated guards enforce tenant ownership before the query
Request parsingCRUD filters, sorting, joins, limits, and pages become a framework query
PersistenceThe ORM executes the query and returns the response envelope

See the API Reference for request parameters and response shapes.

Last updated on
PlatformGenerated code