Skip to main content

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:

KindWhat it creates
postgresA managed PostgreSQL service
filesAn S3-compatible object storage bucket
authEnd-user authentication wired to the app (no standalone service)
appA 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.

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:

ActionMeaning
createResource does not exist yet; will be provisioned
updateSpec changed; a safe in-place update will be applied (app image and env only in Phase 1)
noopResource is unchanged and running; no action taken
unmanagedResource 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​