Framework Overview

The FoundryDB Framework is a code-first, declarative deploy engine. You describe your entire project in a single foundry.config.ts file: the databases it needs, the files bucket, the auth layer, the application container, and how they connect. One command deploys and wires all of it.

The counterpart CLI, create-foundry-app (available at github.com/foundrydb/foundry-framework), scaffolds a new project and compiles your TypeScript config into a ProjectDescriptor. That descriptor is what the platform's Projects API actually receives and acts on.

What the framework manages

A project is a named, re-deployable grouping of platform resources. Four resource kinds are available:

Kind	What it creates
postgres	A managed PostgreSQL service
files	An S3-compatible object storage bucket
auth	End-user authentication wired to the app (no standalone service)
app	A hosted application container

Every project requires exactly one app resource. The other kinds are optional and can be combined freely.

The engine provisions these resources through the same brokered service APIs you would call yourself. It adds no new provisioning path; it only orchestrates the existing APIs in the right order and injects the credentials each resource needs.

Connection wiring is automatic

You do not construct connection strings by hand. The engine wires attachments between resources and injects the credentials directly into the app container's environment:

• Database: DATABASE_URL (when exactly one database is attached). When multiple databases are attached each gets a prefixed set of variables derived from the service name.
• Files: S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET (when exactly one files service is attached). With multiple files attachments each gets a prefixed set: {NAME}_S3_ENDPOINT, {NAME}_S3_BUCKET, {NAME}_S3_ACCESS_KEY_ID, {NAME}_S3_SECRET_ACCESS_KEY.
• Platform API: FOUNDRY_API_TOKEN and FOUNDRY_API_URL are always injected, giving the app a least-privilege scoped token to call back into FoundryDB (for example, to read its own service status or list files).

The FOUNDRY_API_TOKEN is minted with read-only scopes (services:read and files:read) scoped to the deploying user. It is never embedded in the application image.

Project lifecycle

POST /projects/deploy, dependency-ordered reconciliation

RUNNING all resources provisioned · env wired

DescriptorPOST /deployfan-out →postgresRunningfilesRunningDATABASE_URL · S3_* · FOUNDRY_API_TOKEN →appRunning

DescriptorPendingProvisioning / wiringRunningDATABASE_URLS3_*auth issuer

A project moves through three lifecycle stages:

1. Declare. You write a foundry.config.ts file describing every resource the project needs: databases, object storage, auth, and the application container. The create-foundry-app CLI compiles this TypeScript descriptor into a ProjectDescriptor JSON payload and posts it to POST /projects/deploy.
2. Deploy. The engine reconciles the descriptor against the current state of the project. Resources are provisioned in dependency order: databases and storage buckets first (they have no dependencies), then auth (which depends on the database), then the app (which depends on everything). Each resource reaches Running before dependent resources begin provisioning. Connection strings and credentials are injected into the app container automatically once all dependencies are live.
3. Update. On subsequent deploys the engine diffs the new descriptor against the current resource state. Unchanged resources receive no action. Changed resources (app image or environment variables in Phase 1) are updated in place. Dropped resources are left untouched and not deleted automatically; use DELETE /projects/{name} to tear down a project.

Re-deploys are idempotent

Submitting the same descriptor twice does nothing. The engine diffs the new descriptor against the current resource state and assigns one of four actions per resource:

Action	Meaning
create	Resource does not exist yet; will be provisioned
update	Spec changed; a safe in-place update will be applied (app image and env only in Phase 1)
noop	Resource is unchanged and running; no action taken
unmanaged	Resource was previously provisioned but is absent from the new descriptor; left untouched

Resources are never deleted automatically when dropped from a descriptor. An explicit DELETE /projects/{name} is required to tear a project down.

First-deploy atomicity

A first deploy is all-or-nothing. If any resource fails before the project has ever reached Running, the engine rolls back by tearing down every resource it created for that deploy. A failed first deploy leaves no orphaned database, bucket, or app behind.

A re-deploy that hits a terminal failure on a new resource records the project as Failed without touching any previously-provisioned healthy resource.

When to use the framework vs the dashboard or SDK

Use the framework when:

• You are building a new application and want infrastructure defined alongside code in version control.
• You need repeatable deploys across environments (staging, production) from the same descriptor.
• You want zero manual wiring: connection strings, credentials, and the platform token injected automatically.

Use the dashboard or API directly when:

• You are managing long-lived database services that exist independently of any application.
• You need fine-grained control over provisioning options not exposed in the framework spec (HA topology, specific storage tiers, cross-zone replication).
• You are integrating FoundryDB into an existing CI/CD pipeline where you already manage credentials yourself.

Next steps

• Project descriptor reference — the full shape of a foundry.config.ts descriptor and every field the engine accepts.
• Deploying a project — POST /projects/deploy semantics, polling, and teardown.