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

# Architecture

> How Brain is built — runtime, tiers, data, UI, observability

# Architecture

Brain is a layered system designed to be built one workflow at a time, on top of a
runtime that gives us multi-user, multi-thread, tracing, and a web UI out of the
box.

This section explains the pieces and the choices behind them.

<CardGroup cols={2}>
  <Card title="Aggregator + Workflow Registry" icon="route" href="/brain/staging/architecture/aggregator-and-workflows">
    The supervisor pattern. How chat, slash commands, and approval clicks all route to the same workflows.
  </Card>

  <Card title="Implementation Tiers" icon="layer-group" href="/brain/staging/architecture/tiers">
    Tier 1 skills, Tier 2 workflows, Tier 3 agents — when to use which.
  </Card>

  <Card title="Runtime" icon="server" href="/brain/staging/architecture/runtime">
    Brain is built on the deer-flow harness. Why, and what it gives us.
  </Card>

  <Card title="Data Integration" icon="database" href="/brain/staging/architecture/data-integration">
    Brain's own Supabase, CutMake's Supabase, the boundary between them.
  </Card>

  <Card title="UI Structure" icon="layout" href="/brain/staging/architecture/ui-structure">
    The four surfaces — Inbox, Ask, Task, Engine — and what each is for.
  </Card>

  <Card title="Observability" icon="chart-line" href="/brain/staging/architecture/observability">
    Tracing, correction logging, eval datasets. The feedback loop in detail.
  </Card>
</CardGroup>

## At a glance

```text theme={null}
┌─────────────────────────────────────────────────────────────┐
│                         UI Surfaces                          │
│         Inbox     |     Ask     |     Task     |   Engine    │
└────────────────────┬────────────────────────────────────────┘
                     │
       chat   ───────┤                                ┌─── slash command
       (default)     ▼                                │     (bypass)
                ┌────────────────────────┐            │
                │  AGGREGATOR AGENT       │            │
                │  Intent → workflow      │            │
                └────────────┬───────────┘            │
                             │                        │
                             ▼                        ▼
┌─────────────────────────────────────────────────────────────┐
│                  WORKFLOW REGISTRY                           │
│   /create-client  /create-style  /generate-bom               │
│   /draft-true-cost  /generate-quotation  /draft-email        │
│   /ask-pipeline  /summarize-style  /find-duplicates  ...     │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────────┐
│              Runtime: deer-flow harness                      │
│   FastAPI gateway · LangGraph-compatible runtime · Next.js   │
│   Multi-user · Multi-thread · Tracing · Studio compat        │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────────┐
│                 Workflows internally use                     │
│   Tier 1: Skills (simple, deterministic)                     │
│   Tier 2: LangGraph workflows (multi-step, approval-gated)   │
│   Tier 3: Full agents (complex reasoning, multimodal)        │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────────┐
│             External services (via stable contracts)         │
│   BOM agent (Ku Kue) · KG service (Andy) · CutMake API       │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────────┐
│                      Data Layer                              │
│   Brain Supabase: drafts, tasks, approvals, corrections      │
│   CutMake Supabase: production records (read direct;         │
│                     writes go through CutMake API)           │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────────────────┐
│                    Observability                             │
│   LangSmith (Phase 1-2) → Langfuse (privacy migration)      │
│   LangGraph Studio · Correction log                          │
└──────────────────────────────────────────────────────────────┘
```

The order of build is bottom-up: runtime → data layer → one workflow → observability
wired to that workflow → next workflow. The aggregator and registry get scaffolded
early (Phase 2) so subsequent workflows compose into them.

## What ships with every feature

The architecture isn't theoretical. Every shipped feature includes:

* **Tracing** through the observability stack
* **Correction logging** for AI drafts vs. human finals
* **A changelog entry** in this documentation
* **A workflow page** here that describes it

If any one of those is missing, the feature isn't done. See [Principles #7](/brain/staging/principles).

## Related

* [Vision](/brain/staging/vision) — the bet behind the architecture
* [Roadmap](/brain/staging/roadmap) — phase order and what's shipping when