Architecture

API deployment architecture in your AWS account

How API services are provisioned, released and operated in your infrastructure — and what remains under your control.

Your API runs in your infrastructure

Each API deploys as a stateless Node.js service with the framework embedded, behind your load balancer and connected to your PostgreSQL database. Scheduled jobs, secrets, logs and event publishing also remain in your environment. There is no platform runtime between your callers and your APIs, and nothing serving your requests runs in someone else’s account — with one nameable exception, below, if we operate Access Management for you.

Two services sit outside that boundary by design. Your identity provider stays where it is: it authenticates callers, issues tokens and holds every credential. Access Management supplies the access decisions your APIs enforce. It is architecturally separate and can run as another service in your environment or be operated for you by agreement. If we operate it for you, that is a vendor dependency in your request path — bounded by the caching and outage posture you choose, and stated here rather than discovered later.

Whether an application is multi-tenant, owner-scoped or used by a single customer, the deployment unit is the API service. Tenants and owners are isolated through the data model; they are not deployed separately.

How deployment works

The deployment process covers two different scenarios: establishing the environment for the first time, and releasing subsequent application changes.

Initial environment setup

The reference deployment establishes the Elastic Beanstalk application and environments, load balancing, PostgreSQL database, networking, secrets, logging, monitoring, scheduled jobs and any required event transport in your AWS account. Identity and access integrations are then connected at their defined boundaries.

The CI/CD pipeline is configured to build a versioned release package and deploy it only after an authorised person approves the production gate. The infrastructure and operational responsibility remain visible: your team can operate the pipeline directly, or CustomAPIs can operate releases under an agreed managed-services arrangement.

How a release reaches production

Approval of a pull request into production starts the CI/CD workflow. The pipeline builds and tests the application, validates its model and route configuration, and creates a versioned release package tied to the source commit and build.

After those checks pass, the pipeline pauses at a manual production approval gate. Nothing is deployed until an authorised person reviews the release and approves it. The release then follows one of two paths, determined by whether its database changes remain compatible with the application version currently serving traffic.

Expand-and-contract is the norm: schema changes are designed to stay compatible, so releases take the online path and destructive cleanup waits for a later release. The maintenance window is the rare exception, for changes that genuinely cannot straddle two versions.

Online blue/green release

Releases with no database change, or with changes that remain compatible with both application versions, use a blue/green deployment:

1. Any required additive or otherwise backward-compatible database migration is applied.
2. The versioned release package is deployed to the green Elastic Beanstalk environment while blue continues serving production traffic.
3. Startup validation, health checks and controlled smoke tests run against green.
4. If the checks pass, production traffic moves to green.
5. The release is monitored while blue remains available as the application rollback target.
6. Blue is retired after the release has completed its observation period.

If green does not pass its checks, production traffic stays on blue. Destructive database cleanup is performed only in a later release, after the previous application version no longer needs the old schema.

Controlled maintenance release

A database change that cannot support both application versions uses a controlled maintenance window:

1. The pipeline reaches the manual production approval gate and waits.
2. The operator places the application into maintenance mode, drains active requests and pauses scheduled or background work.
3. Once maintenance mode is confirmed, the operator approves the deployment.
4. The database is backed up and the migration is applied.
5. The new versioned package is deployed to Elastic Beanstalk.
6. Startup validation, health checks and deployment smoke tests run before traffic resumes.
7. After the new deployment is verified, background work resumes and the operator removes maintenance mode.

Breaking database changes carry an explicit roll-forward or database-restore plan. Switching back to the previous application package alone may not undo a schema change, so the recovery path is agreed before the production gate is approved.

PostgreSQL is the only hard runtime dependency

PostgreSQL is the only hard runtime dependency. Your schema stays yours: you own it and migrate it with your own tooling, and the framework never alters it. Optional framework infrastructure, such as the audit store, is added only through a deliberate deployment decision; nothing reaches your database without it. You apply the audit store’s SQL with your own migration tooling; under the partitioned profile the framework manages that store’s partitions — its own tables, never yours.

Pluggable identity, events, caching, audit and logging

Every external concern is a pluggable seam with a working default, so the absence of an infrastructure decision does not block adoption:

• Identity resolution — a local resolver by default, or a central identity service through the same seam.
• Event publishing — off by default; connect your event infrastructure when required.
• Identity cache — in-process by default; use a shared store when the fleet requires it.
• Audit storage — the shipped audit store by default, with a custom sink available behind the same seam.
• Logs — standard output by default, with your production log aggregation connected through the log transport.

The defaults provide a safe starting posture. A production deployment replaces only the seams its architecture requires, allowing a service to move from standalone to centrally governed as its needs grow.

API deployment trust boundaries

Each boundary has an explicit security and failure posture:

• Callers reach an API with a token issued by your identity provider and verified at the edge of every request.
• The request path makes at most one hot-path external identity-resolution call behind a cache. Failure denies; it never grants.
• Events travel outbound only, and only after the transaction commits — see event distribution.
• The database remains on your private network, owned, operated and backed up in your account.
• Production deployment remains behind a manual approval gate, with the release package, approver and outcome recorded.

Caching behaviour and the permission-revocation window are described on the identity page.

Rate limiting, IP reputation and edge protection are deliberately not framework concerns: they belong at the load balancer or gateway, where abusive traffic is shed before it reaches an application process at all.

Horizontal scaling and fail-closed releases

API services are stateless and scale horizontally without node-local coordination.

Failure behaviour is deny-shaped from end to end: identity failure denies by default, cache failure denies, and an application release that violates the declared data-model or route contract refuses to start. During a blue/green release, a version that fails validation or health checks never receives production traffic. During a maintenance release, traffic remains stopped until the replacement deployment has been verified.

When an instance is lost, only best-effort work goes with it: never a committed write and never an audit record configured to ride inside its transaction.

Keep API data in your chosen AWS region

Data residency follows from the deployment shape rather than a platform configuration switch. Business data, audit records and logs remain in your account because there is nowhere else for them to go. You select the AWS region and infrastructure controls required by your customers or regulators.

Observability across releases, logs, audit and events

Every response carries a request identifier, including failures. A correlation identifier joins an action’s log lines, audit record and emitted events, allowing one incident to be traced across all three. Structured logs flow through the pluggable transport to the aggregation system you already operate.

Each production release is also traceable to its source commit, versioned package, approval, target environment and deployment result. Health and smoke-test outcomes determine whether traffic moves or maintenance mode is removed.

The framework is a library inside a stateless Node.js service, so it runs on whatever you operate. The reference deployment is AWS Elastic Beanstalk with RDS PostgreSQL; other targets can be agreed where the application’s requirements justify them.