Concepts
How Brokr thinks about infrastructure. Intent in, working stack out. These are the mental models behind every command.
Intent Compilation
Brokr is an intent compiler for infrastructure. You say what you want — "I need a web app with a database" — and Brokr compiles that intent into a concrete infrastructure plan: which providers, which capabilities, which credentials, which DNS records.
The compilation pipeline: intent → CommandPlan → provider resolution → capability provisioning → env injection → deployment. Whether you type canonical CLI syntax, use an alias, or write natural language, all three routes produce the same structured CommandPlan.
Stack Architecture
A stack is a named collection of capabilities wired to real providers. A typical web-app stack includes:
| Layer | What it is |
|---|---|
| Repo | GitHub repository (Brokr-managed or user-managed) |
| Deployment | Vercel project with Git integration |
| Database | Neon Postgres with connection string |
| Storage | Cloudflare R2 bucket with presigned URLs |
| Resend with verified domain | |
| DNS | {name}.brokr.sh subdomain + optional custom domain |
| AI | Gateway access to Claude, GPT, Deepseek |
Each layer is optional — you can create a stack with just a repo and deployment, then add capabilities later with brokr add.
Capability Model
Capabilities are the atomic units of infrastructure. Each has a type, a provider, and a status.
| Type | Default Provider |
|---|---|
database | Neon |
deployment | Vercel |
email | Resend |
repo | GitHub |
ai_provider | Brokr AI Gateway |
kv_store | Upstash Redis |
storage | Cloudflare R2 |
auth | Brokr Auth |
Status lifecycle: requested → provisioning → active → error. Use brokr status --watch to track progress.
Repo Modes
Git is a source-of-code layer in Brokr, not the center of gravity. Two operating modes:
| Mode | Behavior | Default mutation |
|---|---|---|
| Brokr-managed | Brokr creates and owns the repo lifecycle. Best for new stacks. | direct |
| User-managed | Brokr attaches infra around your existing repo without taking it over. | pr-only |
Brokr auto-detects: if you run brokr create from a directory with a GitHub remote, it defaults to user-managed. Otherwise, it creates a new Brokr-managed repo.
Use brokr fork git to fork a Brokr-managed repo into your account (non-destructive), or brokr transfer git to transfer full ownership (irreversible).
Mutation Policies
Mutation policy controls how aggressively Brokr is allowed to write to source control:
| Policy | Behavior |
|---|---|
direct | Brokr commits and pushes directly to the default branch. |
branch | Brokr creates a branch for changes, merges when safe. |
pr-only | Brokr opens a PR for review. Never pushes directly. |
brokr create web-app --repo current --mutation pr-only
.env.brokr
.env.brokr is the sole source of truth for all stack environment variables. Not the database. Not .env. Not Vercel.
The flow: provisioning writes vars into .env.brokr. User vars from .env merge in. brokr deploy reads from .env.brokr and pushes to Vercel. The DB stores a copy for the dashboard UI, but is never the deployment source.
.env.brokr is gitignored. If it's missing a value, the fix is in provisioning — never fall back to the DB.
Gateway Architecture
The Brokr gateway (api.brokr.sh) is a Cloudflare Worker that sits between your app and all backend providers. It handles:
| Function | What it does |
|---|---|
| Authentication | Validates BROKR_TOKEN, resolves per-stack config |
| AI routing | OpenAI-compatible endpoint, routes to Claude/GPT/Deepseek |
| Storage | Signs presigned URLs for R2 uploads and downloads |
| Resolves Resend API key and from domain server-side | |
| Rate limiting | Per-stack, per-capability rate limits |
Your app never touches provider credentials. The gateway resolves them from the stack config and injects them into upstream requests. One token, all services.