Skip to content
THOSAN ONE

Architecture

Claude reasons. Policy decides. The founder approves. Workers execute.

THOSAN ONE separates reasoning, execution and governance so that a capable model can do real work inside limits a founder can trust. This page describes the target architecture and marks exactly what exists in the prototype today.

Layers

Claude is the reasoning brain. Agents are the specialized workforce. Tools are the hands. Business Memory is the organizational memory. The Control Room is the management and governance layer. Workers are the execution layer.

Founder

Sets direction

  • Goals
  • Constraints
  • Budgets
  • Approval rules

Control Room

Management & governance

  • Projects
  • Jobs
  • Policy engine
  • Approval gates
  • Audit log

Claude

Reasoning brain

  • Synthesize signals
  • Evaluate
  • Plan & decompose
  • Select tools
  • Decide next action

Agents

Specialized workforce

  • Market Analyst
  • Opportunity Scout
  • Strategist
  • Content Producer
  • Customer Concierge
  • Sales Assistant
  • +4

Tools & Workers

Hands & execution layer

  • Tool adapters
  • Job queue
  • Workers
  • Event bus

Business Memory

Organizational memory

  • Decisions
  • Outcomes
  • Lessons
  • Reusable context

Outcomes flow back up: measured results are written to Business Memory, and Claude reads them before the next decision.

Implemented vs planned

We only describe as built what is in the repository today.

  • Frontend — Next.js, TypeScript, Tailwind CSS

    Public site and /app with 16 modules on labelled sample data.

    Implemented

  • Claude reasoning layer

    Typed tasks, Zod-validated structured outputs, demo fallback without an API key.

    Implemented

  • Policy engine

    Deterministic risk classification and approval gates. Unit-tested.

    Implemented

  • Job state machine & audit log model

    In-memory in the prototype. Unit-tested.

    Implemented

  • Human Approval Queue

    UI driven by the policy engine; decisions are not persisted yet.

    Prototype

  • Agent orchestration & specialized agents

    Prototype exposes single reasoning tasks; multi-step orchestration is next.

    Planned

  • Event bus, job queue, workers

    Postgres-backed queue first; Redis if needed.

    Planned

  • Tool adapters

    Read-only sources and inbox ingest first. Publishing, messaging, CRM, payments behind gates.

    Planned

  • Persistent business memory

    Postgres.

    Planned

  • Permissions, auth, observability

    Per-agent tool allow-lists; traces with token and cost accounting.

    Planned

  • Evaluation layer & outcome tracking

    Score Claude's outputs against real outcomes from internal dogfooding.

    Planned

System overview

The founder works in the /app prototype. Requests that need judgment go through the API layer to the Claude reasoning layer, which returns a structured proposal validated by a Zod schema. Any proposal with an external effect passes through the deterministic policy engine, which decides the risk level and whether a human must approve. Approved work becomes a job in the Control Room state machine; in the target architecture jobs are dispatched over an event bus and queue to workers, which call tool adapters. Every step writes to an append-only audit log. Results flow into outcome tracking, are evaluated, distilled into lessons in business memory, and fed back as context into the next plan. In the prototype, the frontend, reasoning endpoint, policy engine, job state machine and audit log model exist; execution, persistence and measurement are planned.

Request flow sequence

Each request names a typed task (evaluate_opportunity, plan_experiment, qualify_lead, suggest_reply, analyze_outcome, next_action). With an API key configured, the reasoning layer calls Claude through the official SDK and validates the structured output against the task's Zod schema; without a key it returns deterministic output clearly labelled as demo. Before anything is returned, proposed actions with external effects are classified by the policy engine, so the UI always tells the founder whether an action can proceed or must wait for approval. Claude proposes; it never executes directly.

Agent execution

Agents are role definitions over the same reasoning layer: each has a scoped instruction set, an allowed tool list, and a view into business memory. The orchestrator asks Claude to decompose a goal into tasks and routes each to the right agent. Agents produce structured proposals, never direct side effects. Proposals go through the policy engine; low-risk internal actions become jobs immediately, anything in an approval class waits in the Human Approval Queue. Workers execute jobs through tool adapters and record results in memory and the audit log. In the prototype, the agents appear in the AI Workforce module with demo data; orchestration and workers are planned.

Approval flow

The policy engine is deterministic code, not a model call, so the gate cannot be talked around by a prompt. It returns a risk level (low, medium, high, critical), a requiresApproval flag and human-readable reasons. The approval classes are fixed: public publishing, payments, financial actions, destructive actions, important customer-facing actions, changes to external systems, sensitive data, and irreversible operations. Approve, edit-and-approve and reject decisions are all written to the audit log. Claude can recommend; only the founder can authorize a gated action.

Memory flow

Business memory stores four kinds of record: decisions (what was decided and why), outcomes (what actually happened), lessons (what we now believe because of it) and reusable context (offers, audiences, voice, constraints). Founder edits and rejections in the approval queue are a first-class signal. The Memory Curator agent distills outcomes and decisions into lessons. When a task runs, a context assembler selects relevant records and passes them to Claude, using its long context window. In the prototype, the Business Memory module shows sample data; persistence is planned.

Learning loop

This is the product's core: decisions, execution and outcomes live in one memory, and outcomes are the input to the next decision. MEASURE records what happened; LEARN asks Claude (analyze_outcome, next_action) to compare expected and actual results and propose what to change. The Learning Loop module in the prototype shows this with demo data; a real loop depends on outcome tracking and the evaluation layer, both planned.

Job state machine

Every unit of work is a job with an explicit state. A job moves queued → planning → running and ends in succeeded, failed or cancelled. Whenever planning or execution reaches an action the policy engine gates, the job enters awaiting_approval and does not proceed until the founder approves; rejection cancels it. Every transition appends an event to the audit log. Terminal states cannot transition further. In the prototype the state machine and audit log are implemented and unit-tested in src/lib/control-room/, held in memory; a persistent, queue-backed version is planned.

Design principles

  1. 1. Claude proposes, policy decides, the founder approves, workers execute.
  2. 2. The approval gate is deterministic code, never a prompt.
  3. 3. Every state change is an append-only event.
  4. 4. Every decision is linked to its outcome.
  5. 5. Demo data is always labelled as demo data.