Get started
Core concepts
The vocabulary of Brunel. Projects, facts and evidence, context, services, blueprints, tiers, versions, catalogs and validation rules, and how they fit together.
Project
A project is one repository conversation: its analyses, its designs, every version and the chat around them. In the API and MCP server a project is identified by its conversationId. Plans count tracked projects, meaning distinct repositories.
Fact and evidence
A fact is something true about the repository, found by a deterministic detector: a language, a framework, a datastore, a queue, a worker, an environment variable name, an existing Dockerfile or Terraform folder. Every fact has:
| Field | Example |
|---|---|
category | language, framework, datastore, middleware, runtime, container, ci, workload, env, integration, scale-hint, existing-infra |
key and value | postgres · 16 |
confidence | 0 to 1 |
evidence | one or more files, with lines and a short excerpt (secrets redacted) |
source | detector, or user when you corrected it |
See Facts and evidence.
Context
The context is what the code cannot tell: traffic, users, data volume, budget, operations skill, availability, compliance, providers and region. Brunel pre-fills it from the facts; you adjust it. Changing the context can trigger a redesign.
Services
From the facts, Brunel identifies the services to deploy: a server-rendered web app, a single-page app, an API, a worker, a cron job, a websocket server or a static site, with their runtime, port and whether they keep state.
Blueprint and tiers
The blueprint is the provider-agnostic design: four tiers (Starter, Growth, Scale, Enterprise), each a graph of components (a relational database, a container service, a CDN, a WAF…) with a size, replicas, high availability, placement and a why: the facts and context that justify it, the alternatives rejected and the trade-off accepted. Component ids stay stable across tiers, so you can follow one component from Starter to Enterprise.
Mapping and pricing
The mapper turns each component into a real service and SKU for the chosen provider (for example a medium relational database into Amazon RDS for PostgreSQL db.t4g.medium). The pricer computes its monthly cost from the provider's official catalog, dated and linked to its sources. See How prices are computed.
Validation rules
Every tier passes a rule-based validator before you see it: databases stay private, secrets are managed, public entry points use TLS, stateful components have backups, logs, metrics and alerting exist, the tier stays within its budget, EU residency keeps every region in the EU, and every service is hosted. A critical violation sends the design back for repair. See Architecture tiers.
Version
Every design and every change is an immutable version with a label, its parent and a diff: components added, removed or changed, and the monthly cost delta. You can compare versions and roll back to any of them.
Deterministic architect and AI reasoning
Brunel works with or without AI. The deterministic architect designs from rules alone (the Free plan uses it). With AI reasoning, a model helps understand the services and design the tiers, but it never writes prices, service names, SKUs or Terraform: its output is a schema-validated blueprint that goes through the same mapper, pricer and validator.