> ## Documentation Index
> Fetch the complete documentation index at: https://backdrift.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```mermaid theme={null}
graph LR
    A[Natural Language] --> B[Spec]
    B --> C[Blueprint]
    C --> D[Infrastructure]
    D --> E[Cloud Resources]
```

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

<Accordion title="View Blueprint Schema">
  ```json theme={null}
  {
    "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"]
        }
      ]
    }
  }
  ```
</Accordion>

## Key Concepts

### Entities

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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?

<CardGroup cols={2}>
  <Card title="Portable" icon="suitcase">
    Blueprints are cloud-agnostic. The same Blueprint could theoretically deploy to different providers.
  </Card>

  <Card title="Version Controlled" icon="git-alt">
    Every change creates a new revision. Roll back to any previous version with one click.
  </Card>

  <Card title="AI-Readable" icon="robot">
    The structured format means AI tools can understand, modify, and validate your backend.
  </Card>

  <Card title="Exportable" icon="download">
    Download the generated Infrastructure-as-Code (CDK) to take full control.
  </Card>
</CardGroup>

## Next Steps

<Card title="Prompting Guide" icon="message" href="/workflow/prompting">
  Learn how to describe your backend effectively.
</Card>