Blueprints

The universal specification that powers everything.

A Blueprint is the heart of every Backdrift project. It’s a structured representation of your backend that describes entities, relationships, authentication, and business logic in a format both humans and AI can understand.

What is a Blueprint?

Think of a Blueprint as the “source of truth” for your backend. It contains:

• Entities - Your data models (Users, Tasks, Projects)
• Relationships - How entities connect (Tasks belong to Projects)
• Authentication - How users sign in and what roles exist
• API Endpoints - What operations are available
• Workflows - Scheduled jobs, events, and long-running processes

The Blueprint Lifecycle

1. Natural Language → You describe what you want
2. Spec → AI creates an editable specification
3. Blueprint → The spec is compiled into a complete Blueprint IR
4. Infrastructure → Blueprint is transformed into cloud resource definitions
5. Cloud Resources → Real infrastructure is deployed

Blueprint Structure

View Blueprint Schema

{
  "project": {
    "name": "Task Manager",
    "description": "A multi-tenant task management application"
  },
  "auth": {
    "strategy": "cognito",
    "roles": ["admin", "member", "viewer"]
  },
  "tenancy": {
    "mode": "multi_tenant",
    "tenant_entity": "organization"
  },
  "entities": [
    {
      "name": "task",
      "fields": [
        { "name": "id", "type": "string", "primary": true },
        { "name": "title", "type": "string" },
        { "name": "priority", "type": "enum", "enum": ["low", "medium", "high"] },
        { "name": "due_date", "type": "datetime" },
        { "name": "org_id", "type": "string" }
      ],
      "tenancy": "tenant"
    }
  ],
  "api": {
    "resources": [
      {
        "entity": "task",
        "base_path": "/v1/tasks",
        "operations": ["list", "create", "get", "update", "delete"]
      }
    ]
  }
}

Key Concepts

Entities

Entities are your data models. Each entity becomes a database table and gets automatic API endpoints.

{
  "name": "task",
  "fields": [
    { "name": "title", "type": "string" },
    { "name": "status", "type": "enum", "enum": ["pending", "done"] },
    { "name": "due_date", "type": "datetime", "nullable": true }
  ]
}

Relationships

Connect entities together with foreign keys:

{
  "name": "task",
  "fields": [
    {
      "name": "project_id",
      "type": "string",
      "foreign_key": { "entity": "project", "field": "id" }
    }
  ]
}

Multi-Tenancy

For SaaS applications, Backdrift automatically isolates data by tenant:

{
  "tenancy": {
    "mode": "multi_tenant",
    "tenant_entity": "organization",
    "tenant_id_field": "org_id"
  }
}

Every query is automatically filtered by the user’s organization—a user in Org A cannot access data from Org B.

Why Blueprints?

Portable

Blueprints are cloud-agnostic. The same Blueprint could theoretically deploy to different providers.

Version Controlled

Every change creates a new revision. Roll back to any previous version with one click.

AI-Readable

The structured format means AI tools can understand, modify, and validate your backend.

Exportable

Download the generated Infrastructure-as-Code (CDK) to take full control.

Next Steps

Prompting Guide

Learn how to describe your backend effectively.