Architecture

This section is for developers and technical leads who need to review what Apso generates, where custom code belongs, how requests are authorized, and how the service behaves after generation.

System boundary

Apso foundation mapOne product contract. A backend your team can own.

Owned output

Product intent

Describe the behavior

Actors, records, permissions, tenant boundaries, and the workflows they need.

Schema contract

Define the model

.apsorc

Entities, fields, relationships, auth strategy, indexes, and scope.

Consistent generation

Build the service

NestJSFastAPIGin

APIs, migrations, guards, tests, infrastructure, and OpenAPI.

Product code

Extend, run, and own

src/extensions/

Add product behavior, connect the client, and deploy wherever you choose.

Repeatable structureReviewable changesPortable codebase

The schema is the input contract. Generated source is replaceable output. Extensions contain product-specific behavior. The repository holds all three so a team can review and run the service with standard framework tooling.

Ownership boundaryRegenerate the foundation. Preserve the product.

No lock-in

Generated from .apsorc

Reproducible foundation

src/autogen/entities/src/autogen/controllers/src/autogen/dtos/migrations/

Change the contract, validate it, and generate the same framework structure again.

Written by your team

Preserved product logic

src/extensions/src/integrations/src/workflows/tests/

Keep approvals, billing rules, integrations, and other product decisions in normal framework code.

The repository, generated source, extension code, and deployment configuration remain available to inspect, change, and run elsewhere.

Topics

Follow schema validation, generation, repository synchronization, and cloud build orchestration

Platform architecture

Review generated layers, ownership rules, and extension points

Generated code

Connect credentials, auth context, tenant scoping, and application authorization

Security model

Measure the service and add database, cache, queue, or replica capacity where evidence calls for it

Scaling

Design principles

Reviewable inputs and outputs

Commit .apsorc, generated code, migrations, extensions, dependencies, and tests. Each schema change must produce a diff that explains the API and database impact.

Preserved product logic

Regeneration can replace autogen/. Keep calculations, approvals, integrations, custom endpoints, and workflow rules in extensions/ so schema iteration does not erase them.

Framework-native runtime

The deployed process is a normal NestJS, FastAPI, or Gin application using its framework and ORM. It can run through Apso Cloud or the deployment model selected by the team.

Explicit security

Authentication identifies the caller. scopeBy applies tenant filters from the auth context. Extensions implement product permissions that require more than record ownership.

Evidence-based operations

Choose indexes, connection pools, caches, queues, and replicas from measured traffic and query behavior. Do not treat generated defaults as a capacity plan.