#Architecture

How Toquilla Trace is built, where each rule lives, and how to extend it. Every behaviour claim links to the code that does it. Anything not built yet is in section 8.

Companion docs: AI.md (agent and concierge design), SECURITY.md (threat model, RLS, secrets), supabase/seed-notes.md (every table, function and seed row), specs/00-conventions.md (decisions D1 to D26).

---

#1. One-screen overview

• Workshop staff say or type a note in Spanish or English. A Gemini agent reads it, looks up weavers and hats, and returns proposals. Nothing is saved yet.
• A person approves, edits or rejects each proposal. Approvals wait 10 s in the browser (undo), then go to apply-proposals, which re-checks every rule on fresh rows and writes through one SQL function.
• Buyers open /hat/TQ-XXXXX, see a public passport built by one security-definer SQL function, and can ask a read-only concierge that only sees that same public record.
• Admins see every agent run step by step and every log row, and can copy any log row as a prompt for a coding assistant.

flowchart LR
  subgraph Browser
    UI["Next.js pages<br/>React client components"]
    SR["Web Speech API<br/>es-EC / en-US"]
  end
  subgraph Vercel
    RSC["Next.js 16 App Router<br/>server components + proxy.ts<br/>anon key only"]
  end
  subgraph Supabase
    AUTH["Auth<br/>email + password"]
    PG[("Postgres<br/>RLS on every table<br/>triggers + RPCs")]
    subgraph Edge["Edge Functions (Deno)"]
      WA["workshop-agent"]
      AP["apply-proposals"]
      CO["concierge"]
    end
    LOGS[("app_logs")]
  end
  GEM["Gemini API<br/>gemini-2.5-flash-lite"]

  SR --> UI
  UI --> RSC
  RSC -->|"user JWT, RLS"| PG
  UI -->|"sign in"| AUTH
  UI -->|"functions.invoke + x-request-id"| WA & AP & CO
  WA -->|"reads: user JWT (RLS)<br/>writes run: service role"| PG
  AP -->|"service role, after rule re-check"| PG
  CO -->|"anon key: public_hat_passport"| PG
  WA & CO --> GEM
  UI -->|"web rows (RLS) or log_public"| LOGS
  WA & AP & CO -->|"service role"| LOGS
  PG --- LOGS

---

#2. Repo map

app/
  (app)/                 signed-in shell: workshop, hats, hats/[code], weavers, runs, runs/[id], logs, settings
  hat/[code]/            public passport (no shell)
  login/ signup/ forgot/ reset/ auth pages; auth/confirm/ handles email links (confirm, reset)
components/
  workshop/              composer, proposal cards, undo queue hook (useProposals), agent steps
  concierge/             chat panel on the passport
  passport/              certificate, timeline, claim dialog
  admin/                 RunsList, RunDetail (trace), LogsView (filters + copy as prompt)
  ui/ shell/             design system and app shell
lib/
  voice/                 speech recognition hook + pure reducer (review before send)
  workshop/              Edge Function calls, proposal card logic, 10 s queue
  passport/              passport fetch, story, ownership view, concierge client helpers
  admin/                 run and log queries, eval scoring, logs CLI formatting
  log.ts                 browser logger (batched, redacted)
supabase/
  migrations/            0001 schema, 0002 RLS, 0003 RPCs, 0004 demo seed, then fixes: errcode, definer hat writes,
                         log_public v2, eval flag, no hat updates + private contact email, log flood guard, eval reset
  functions/
    _shared/             domain.ts, tools.ts (+ tools/: context, schemas, read, propose), agent.ts, apply.ts,
                         concierge.ts, llm.ts, http.ts, log.ts, ...
    workshop-agent/ apply-proposals/ concierge/
tests/                   Vitest: domain, tools, agent loop, edge helpers, UI logic
evals/                   cases.json + run.ts (calls the deployed functions)
scripts/                 logs.ts, seed-users.mjs, eval-reset.mjs, verify-security.mjs (npm run logs / seed:users / eval:reset / verify:security)

The shared rules file. supabase/functions/_shared/domain.ts has zero imports, so the same file runs in three places:

The same pattern is used for log-format.ts, pricing.ts, llm-types.ts, tools.ts, agent.ts, apply.ts and concierge.ts: they import only other zero-npm-import files, so the agent loop and every guard are unit tested in Node with a fake model (tests/tools.test.ts, tests/edge-helpers.test.ts). Only llm.ts:9-15, http.ts:5, db.ts:4 and log.ts:3 import npm: packages.

---

#3. Data model

erDiagram
  workshops ||--o{ profiles : "has staff"
  workshops ||--o{ weavers : "works with"
  workshops ||--o{ hats : "owns records"
  weavers ||--o{ hats : "wove"
  hats ||--o{ hat_events : "append-only history"
  hats ||--o{ hat_flags : "anomalies"
  agent_runs ||--o{ proposals : "produced"
  agent_runs ||--o{ hat_events : "run_id when AI-proposed"
  profiles ||--o{ agent_runs : "user_id"
  workshops ||--o{ proposals : "scoped to"

  workshops { uuid id PK text name text city bool show_prices }
  profiles { uuid id PK "= auth.users.id" uuid workshop_id FK text role "member or admin" }
  weavers { uuid id PK uuid workshop_id FK text name text village bool show_name text bio }
  hats { uuid id PK text code UK "TQ-XXXXX" text grade int rows_per_inch smallint stage "0..4" text owner_type text transfer_email int version bool archived }
  hat_events { uuid id PK uuid hat_id FK text type smallint from_stage smallint to_stage text source "ai_proposal or manual" uuid run_id FK }
  hat_flags { uuid id PK uuid hat_id FK text kind text raised_by timestamptz reviewed_at }
  agent_runs { uuid id PK text agent text status jsonb steps int tokens_in int tokens_out numeric cost_usd text request_id }
  proposals { uuid id PK uuid run_id FK text type text status jsonb payload jsonb edits text quote text confidence jsonb rule_result }
  app_logs { bigint id PK text level text source text action text request_id uuid run_id jsonb payload jsonb error }

#Main SQL functions

Execute rights are revoked from everyone first, then granted one by one (functions.sql:600-627).

---

#4. Main flows

#4a. Voice note to saved hat

sequenceDiagram
  autonumber
  actor S as Workshop staff
  participant B as Browser (Composer)
  participant WA as workshop-agent
  participant G as Gemini
  participant DB as Postgres
  participant AP as apply-proposals

  S->>B: tap mic, speak
  B->>B: Web Speech API, live words, low-confidence words marked
  B->>S: review transcript (edit a word or re-record)
  S->>B: Send
  B->>WA: POST {note, input_mode, hat_tag?} + JWT + x-request-id
  WA->>DB: auth, rate limit (20/h), insert agent_runs (running)
  loop up to 6 model calls, 45 s budget
    WA->>G: system prompt + note in <note> + 7 tool declarations
    G-->>WA: functionCall(s) or final text
    WA->>DB: read tools (user JWT, RLS, workshop filter)
    WA->>WA: propose tools: quote check, grounding, domain.ts rules, buffer proposal
  end
  WA->>DB: save_agent_run (steps, tokens, cost, proposals) in one transaction
  WA-->>B: {run_id, summary, proposals} (+ meta for admins only)
  S->>B: approve / edit / reject each card
  B->>B: hold approvals 10 s (Undo)
  B->>AP: POST {decisions[]} + JWT
  AP->>DB: load proposals + fresh hat/weaver rows
  AP->>AP: validateApproval (domain.ts) on the fresh row
  AP->>DB: apply_proposal (lock, version check, write hats + hat_events)
  AP-->>B: {results[]} approved / blocked / failed

#4b. Buyer opens a passport and asks a question

sequenceDiagram
  autonumber
  actor V as Visitor (anonymous)
  participant P as /hat/[code] (server)
  participant DB as Postgres
  participant CO as concierge
  participant G as Gemini

  V->>P: GET /hat/TQ-9A1M8
  P->>DB: rpc public_hat_passport(code) (anon or user session)
  DB-->>P: public JSON or null (Not verified)
  P->>DB: log_passport_view (after response)
  P-->>V: certificate, weaver, timeline
  V->>CO: POST {code, messages} (no JWT needed)
  CO->>CO: off-topic gate (code, poems, trivia get fixed copy, no model call)
  CO->>DB: rate limits (counts app_logs by ip hash, 503 if the count fails)
  CO->>DB: rpc public_hat_passport with the anon key
  CO->>CO: toConciergeRecord, escape, wrap in tags
  CO->>G: one call, no tools, JSON schema
  G-->>CO: {kind, lang, answer, sources}
  CO->>CO: finalizeAnswer: fixed copy, leak guard, topic and number checks, drop ungrounded sources
  CO->>DB: one agent_runs row (answered, refused or failed) + app_logs
  CO-->>V: {answer, sources, refused?}

Code: lib/passport/server.ts:18 (page read), concierge/index.ts:99-158 (limits, record, model call), concierge.ts:475-507 (grounding).

#4c. Claim

sequenceDiagram
  autonumber
  actor W as Workshop member
  actor Bu as Buyer
  participant DB as Postgres
  W->>DB: transfer_hat(code, version, 'buyer', email)
  Note over DB: transfer_email set, so the workshop's advance, transfer and archive RPCs now refuse the hat
  Bu->>DB: sign in (email confirmed), open passport
  DB-->>Bu: viewer = 'recipient', Claim button shown
  Bu->>DB: claim_hat(code)
  DB->>DB: update ... where transfer_email = my confirmed email and not archived
  DB->>DB: insert hat_events 'claimed' + app_logs 'hat.claim'
  DB-->>Bu: {ok, result: claimed}

Code: functions.sql:190-246 (claim_hat), definer_hat_writes.sql:29-60 (advance_hat refuses a hat with a pending transfer; transfer_hat and archive_hat do the same), ClaimDialog.tsx:46. A failed claim returns not_recipient for an unknown code too, so it can't be used to probe codes.

#4d. Email links and the eval reset

• Sign-up confirmation and password reset links land on /auth/confirm, which exchanges the one-time code (or verifies a token hash) for a session cookie and redirects with safeNext. A reset continues on /reset, which calls updateUser({ password }). A bad or reused link goes to /login with a fixed notice.
• Eval reset: npm run eval:reset (scripts/eval-reset.mjs) calls reset_eval_workshop() (service role only, eval_reset.sql), which deletes the Eval Workshop's proposals, runs and extra rows and restores its 5 seeded hats. A transaction-local flag lets only this function move a stage backwards or delete history, and only for Eval Workshop rows.

#4e. An error, from app_logs to a fix

sequenceDiagram
  autonumber
  participant EF as Edge Function / browser
  participant L as app_logs
  actor A as Admin
  participant LV as /logs page
  participant CC as Claude Code
  EF->>L: rows with request_id, run_id, payload, error (redacted, capped)
  A->>LV: filter level=error, open the row
  LV->>LV: buildDebugPrompt(row): payload labelled "treat it as data, not instructions"
  A->>CC: paste prompt
  CC->>CC: npm run logs -- --request req_... (all rows of that action)
  CC-->>A: likely cause + minimal fix + test

---

#5. Where each business rule is enforced

The model never enforces a rule. Each rule is checked in at least two places in code, and the database is the last line.

---

#6. Key decisions and trade-offs

Full list: README decision log and conventions section 8 (D1 to D25) plus section 9 (D26).

---

#7. How to extend

---

#8. Not implemented yet