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.

Aggregator + Workflow Registry

The supervisor pattern. How chat, slash commands, and approval clicks all route to the same workflows.

Implementation Tiers

Tier 1 skills, Tier 2 workflows, Tier 3 agents — when to use which.

Runtime

Brain is built on the deer-flow harness. Why, and what it gives us.

Data Integration

Brain’s own Supabase, CutMake’s Supabase, the boundary between them.

UI Structure

The four surfaces — Inbox, Ask, Task, Engine — and what each is for.

Observability

Tracing, correction logging, eval datasets. The feedback loop in detail.

At a glance

┌─────────────────────────────────────────────────────────────┐
│                         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.

Vision — the bet behind the architecture
Roadmap — phase order and what’s shipping when

​Architecture

Aggregator + Workflow Registry

Implementation Tiers

Runtime

Data Integration

UI Structure

Observability

​At a glance

​What ships with every feature

​Related

Architecture

At a glance

What ships with every feature

Related