# antonaios/anton architecture

> Architecture diagram of the GitHub repository antonaios/anton, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/antonaios/anton
- Repository: https://github.com/antonaios/anton

## Overview

1. **Overall shape**
   - This is a local-first, operator-driven system for M&A/investment workflows.
   - The repository is split into four main runtime areas: `routines/` as the FastAPI bridge and orchestration core, `dashboard/` as the React cockpit, `engine/` as the deterministic valuation layer, and `vault/` as the canonical Markdown memory store.
   - The key architectural rule is boundary separation: components communicate through the filesystem, HTTP, or subprocesses, not by importing each other across layers.

2. **The vault is the system of record**
   - `vault/` is an Obsidian-style Markdown repository with YAML frontmatter.
   - It holds the operator’s memory, project notes, templates, decisions, and source registers.
   - Writes to the vault are treated as governed, append-oriented memory updates rather than silent database mutations.

3. **`routines/` is the bridge and control plane**
   - This is the central Python backend, exposing many HTTP routes and also hosting CLI-driven automation.
   - It owns dispatch, routing, budgets, telemetry, session locking, credentials management, and the sensitivity guard.
   - It is the only layer that touches most other subsystems, making it the main architectural hub.

4. **Governance is a first-class subsystem**
   - The system is built around pre-dispatch control: sensitivity, plan tier, and budget checks happen before a model or crew runs.
   - The governance core enforces lane eligibility, cost ceilings, and audit logging, and it fails closed when sensitivity is unclear.
   - This is what keeps confidential or MNPI work from leaking into a cloud path.

5. **The four execution lanes**
   - The backend supports distinct lanes: chat, single skill, composite actions, and autonomous crews.
   - Chat is a direct conversational path; single skills are governed route-to-action workflows; composite actions are multi-step DAG-like workflows; crews are multi-role subprocess agents.
   - The lanes differ in determinism, latency, and audit shape, but all pass through the same governance boundary.

6. **Deterministic valuation is isolated in `engine/`**
   - `engine/` is a separate Python package for valuation workflows like LBO, comps, and related Excel-driven templates.
   - It uses a registry/cell-map style model to drive versioned spreadsheet templates cell-by-cell.
   - The important architectural point is that the LLM does not compute the numbers; it only supplies or narrates inputs, while Python executes the math deterministically.

7. **The dashboard is a thin operator cockpit**
   - `dashboard/` is a React + TypeScript + Vite application.
   - It renders the operator workspace: chat, project panels, workflow drawers, budget/status cards, and tabs for skills, runs, inbox items, and governance views.
   - Its job is presentation and command entry; the actual business logic stays in the backend.

8. **Routines are organized by business capability**
   - Under `routines/routines/`, the code is split into domains such as budgets, credentials, daily digest, earnings, intake, project chat, recall, sectors, skills, vault graph, vault health, scheduler, and more.
   - This structure indicates a service-oriented monolith rather than many deployed microservices.
   - Each capability has its own data model, CLI entry points, and often one or more API routes.

9. **Skills and crews provide the AI execution model**
   - `routines/routines/skills/` contains governed skill packages, each with references, scripts, test inputs/outputs, and runtime wrappers.
   - `routines/crews_src/` contains heavier autonomous agent workflows such as triage, explore, debate, and digest.
   - The runtime layer includes caps, deduping, guardrails, and gateway logic so model calls are centrally governed.

10. **Ingestion and synthesis flow into the vault**
    - Multiple subsystems pull in external or operator-provided material: PDFs, newsletters, meeting notes, market data, research, and daily briefs.
    - These pipelines usually parse or extract source material, synthesize a structured output, and then write governed Markdown artifacts back into the vault.
    - The flow is typically source material → extraction/synthesis in routines → approved write to vault.

11. **Search, recall, and knowledge health are separate from generation**
    - The repo includes recall, vault graph, vault health, and lessons/learning modules that analyze existing content rather than generate new deal outputs.
    - These subsystems index, query, cluster, deduplicate, and propose improvements to the operator’s knowledge base.
    - This separates memory inspection and system improvement from live deal execution.

12. **Budgets, telemetry, and sessions are operational controls**
    - Budget enforcement is explicit and scoped globally, per model, or per project.
    - Telemetry and audit routes record structured run metadata such as provider, model, sensitivity tier, and cost.
    - Session and lock management prevent conflicting operator actions and keep each engagement’s state coherent.

13. **External dependencies matter, but are compartmentalized**
    - The system is designed to work with local LLMs via Ollama for sensitive work, and can also route to cloud providers when policy allows.
    - The valuation engine expects Excel automation support on the host, which is why the project is Windows-first in practice.
    - Some optional market/news routines integrate with external data providers, but these are clearly separated from core vault and valuation logic.

14. **What an architecture diagram should emphasize**
    - Put `routines/` in the center as the governing hub.
    - Show `vault/` as the canonical data store and `engine/` as a separate deterministic compute island.
    - Place `dashboard/` as the user-facing client over HTTP.
    - Draw distinct lanes for ingest, governed model calls, deterministic valuation, and autonomous crews, all constrained by the same sensitivity and budget controls.

Main entry points: [`routines/routines/api/routes`](https://github.com/antonaios/anton/tree/main/routines/routines/api/routes) (Route Layer), [`vault/Projects/_template/00 Brief.md`](https://github.com/antonaios/anton/blob/HEAD/vault/Projects/_template/00%20Brief.md) (Markdown Vault), [`engine/valuation/__init__.py`](https://github.com/antonaios/anton/blob/main/engine/valuation/__init__.py) (Valuation Engine), [`routines/routines/api/app.py`](https://github.com/antonaios/anton/blob/main/routines/routines/api/app.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_dashboard["Dashboard"]
  node_n_dashboard["Operator UI<br/>react-vite app<br/>[App.tsx]"]
  node_n_dashboard_api["API Client<br/>ts transport<br/>[api.ts]"]
  node_n_dashboard_panels["Workspace Panels<br/>ui components"]
end

subgraph group_g_routines["Routines"]
  node_n_api["HTTP API<br/>fastapi app<br/>[app.py]"]
  node_n_api_routes["Route Layer<br/>api routes"]
  node_n_governance["Governance<br/>guards and policy<br/>[security.py]"]
  node_n_budgets["Budgets<br/>policy gate<br/>[gate.py]"]
  node_n_sessions["Sessions<br/>lock control<br/>[session_lock.py]"]
  node_n_skills["Skills Runtime<br/>governed skills<br/>[llm_gateway.py]"]
  node_n_crews["Crew Flows<br/>subprocess agents<br/>[triage_crew.py]"]
  node_n_ingest["Ingestion<br/>capture pipelines<br/>[dispatch.py]"]
  node_n_recall["Recall<br/>knowledge retrieval<br/>[retrieve.py]"]
  node_n_health["Vault Health<br/>knowledge QA<br/>[constitution.py]"]
  node_n_vault_graph["Vault Graph<br/>knowledge graph<br/>[graph.py]"]
  node_n_scheduler["Scheduler<br/>job runner<br/>[scheduler.py]"]
end

subgraph group_g_engine["Engine"]
  node_n_engine["Valuation Engine<br/>python package<br/>[__init__.py]"]
  node_n_registry["Template Registry<br/>cell mapping<br/>[registry.py]"]
  node_n_excel["Excel Driver<br/>spreadsheet executor<br/>[excel_engine.py]"]
end

subgraph group_g_vault["Vault"]
  node_n_vault["Markdown Vault<br/>obsidian repo<br/>[00 Brief.md]"]
  node_n_vault_templates["Templates<br/>[company.md]"]
  node_n_project_template["Project Skeleton<br/>project structure"]
end

node_n_dashboard -->|"calls"| node_n_dashboard_api
node_n_dashboard -->|"renders"| node_n_dashboard_panels
node_n_dashboard_api -->|"HTTP"| node_n_api
node_n_api -->|"mounts"| node_n_api_routes
node_n_api -->|"wraps"| node_n_governance
node_n_governance -->|"checks"| node_n_budgets
node_n_governance -->|"locks"| node_n_sessions
node_n_api_routes -->|"dispatches"| node_n_skills
node_n_api_routes -->|"spawns"| node_n_crews
node_n_api_routes -->|"runs"| node_n_ingest
node_n_api_routes -->|"queries"| node_n_recall
node_n_api_routes -->|"audits"| node_n_health
node_n_api_routes -->|"inspects"| node_n_vault_graph
node_n_api_routes -->|"schedules"| node_n_scheduler
node_n_ingest -->|"writes"| node_n_vault
node_n_recall -->|"reads"| node_n_vault
node_n_health -->|"checks"| node_n_vault
node_n_vault_graph -->|"parses"| node_n_vault
node_n_skills -->|"supplies inputs"| node_n_engine
node_n_engine -->|"uses"| node_n_registry
node_n_engine -->|"executes"| node_n_excel
node_n_engine -->|"exports"| node_n_vault
node_n_vault_templates -->|"defines"| node_n_project_template
node_n_vault -->|"contains"| node_n_vault_templates

click node_n_dashboard "https://github.com/antonaios/anton/blob/main/dashboard/src/App.tsx"
click node_n_dashboard_api "https://github.com/antonaios/anton/blob/main/dashboard/src/lib/api.ts"
click node_n_dashboard_panels "https://github.com/antonaios/anton/tree/main/dashboard/src/components"
click node_n_api "https://github.com/antonaios/anton/blob/main/routines/routines/api/app.py"
click node_n_api_routes "https://github.com/antonaios/anton/tree/main/routines/routines/api/routes"
click node_n_governance "https://github.com/antonaios/anton/blob/main/routines/routines/api/middleware/security.py"
click node_n_budgets "https://github.com/antonaios/anton/blob/main/routines/routines/budgets/gate.py"
click node_n_sessions "https://github.com/antonaios/anton/blob/main/routines/routines/api/middleware/session_lock.py"
click node_n_skills "https://github.com/antonaios/anton/blob/main/routines/routines/skills/_runtime/llm_gateway.py"
click node_n_crews "https://github.com/antonaios/anton/blob/main/routines/crews_src/triage_crew.py"
click node_n_ingest "https://github.com/antonaios/anton/blob/main/routines/routines/intake/dispatch.py"
click node_n_recall "https://github.com/antonaios/anton/blob/main/routines/routines/recall/retrieve.py"
click node_n_health "https://github.com/antonaios/anton/blob/main/routines/routines/vault_health/constitution.py"
click node_n_vault_graph "https://github.com/antonaios/anton/blob/main/routines/routines/vault_graph/graph.py"
click node_n_scheduler "https://github.com/antonaios/anton/blob/main/routines/routines/scheduler/scheduler.py"
click node_n_engine "https://github.com/antonaios/anton/blob/main/engine/valuation/__init__.py"
click node_n_registry "https://github.com/antonaios/anton/blob/main/engine/valuation/registry.py"
click node_n_excel "https://github.com/antonaios/anton/blob/main/engine/valuation/excel_engine.py"
click node_n_vault "https://github.com/antonaios/anton/blob/main/vault/Projects/_template/00 Brief.md"
click node_n_vault_templates "https://github.com/antonaios/anton/blob/main/vault/Templates/company.md"
click node_n_project_template "https://github.com/antonaios/anton/blob/main/vault/Projects/_template/01 Source Register.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_dashboard,node_n_dashboard_api,node_n_dashboard_panels toneBlue
class node_n_api,node_n_api_routes,node_n_governance,node_n_budgets,node_n_sessions,node_n_skills,node_n_crews,node_n_ingest,node_n_recall,node_n_health,node_n_vault_graph,node_n_scheduler toneAmber
class node_n_engine,node_n_registry,node_n_excel toneMint
class node_n_vault,node_n_vault_templates,node_n_project_template toneRose
```

## Components

### Dashboard

React operator cockpit

- [Operator UI](https://github.com/antonaios/anton/blob/main/dashboard/src/App.tsx): react-vite app · Thin client for chat, runs, projects, and governance · `dashboard/src/App.tsx`
- [API Client](https://github.com/antonaios/anton/blob/main/dashboard/src/lib/api.ts): ts transport · Browser-side wiring for backend routes and sessions · `dashboard/src/lib/api.ts`
- [Workspace Panels](https://github.com/antonaios/anton/tree/main/dashboard/src/components): ui components · Chat, project, budget, routing, and workflow surfaces · `dashboard/src/components`

### Routines

Python control plane and workflows

- [HTTP API](https://github.com/antonaios/anton/blob/main/routines/routines/api/app.py): fastapi app · Main backend entrypoint for routes and middleware · `routines/routines/api/app.py`
- [Route Layer](https://github.com/antonaios/anton/tree/main/routines/routines/api/routes): api routes · Business capability endpoints for skills, vault, budgets, and operations · `routines/routines/api/routes`
- [Governance](https://github.com/antonaios/anton/blob/main/routines/routines/api/middleware/security.py): guards and policy · Sensitivity, budget, session lock, and security checks before execution · `routines/routines/api/middleware/security.py`
- [Budgets](https://github.com/antonaios/anton/blob/main/routines/routines/budgets/gate.py): policy gate · Cost ceilings, incidents, and enforcement rules · `routines/routines/budgets/gate.py`
- [Sessions](https://github.com/antonaios/anton/blob/main/routines/routines/api/middleware/session_lock.py): lock control · Session locks and operator state coherence · `routines/routines/api/middleware/session_lock.py`
- [Skills Runtime](https://github.com/antonaios/anton/blob/main/routines/routines/skills/_runtime/llm_gateway.py): governed skills · Registry, caps, dedupe, guardrails, and LLM gateway · `routines/routines/skills/_runtime/llm_gateway.py`
- [Crew Flows](https://github.com/antonaios/anton/blob/main/routines/crews_src/triage_crew.py): subprocess agents · Autonomous multi-role workflows for triage, debate, explore, and digest · `routines/crews_src/triage_crew.py`
- [Ingestion](https://github.com/antonaios/anton/blob/main/routines/routines/intake/dispatch.py): capture pipelines · Pull, parse, synthesize, and write source material · `routines/routines/intake/dispatch.py`
- [Recall](https://github.com/antonaios/anton/blob/main/routines/routines/recall/retrieve.py): knowledge retrieval · Index, rerank, and synthesize existing vault content · `routines/routines/recall/retrieve.py`
- [Vault Health](https://github.com/antonaios/anton/blob/main/routines/routines/vault_health/constitution.py): knowledge QA · Freshness, links, speculation, and constitution checks · `routines/routines/vault_health/constitution.py`
- [Vault Graph](https://github.com/antonaios/anton/blob/main/routines/routines/vault_graph/graph.py): knowledge graph · Graph extraction and query layer over vault notes · `routines/routines/vault_graph/graph.py`
- [Scheduler](https://github.com/antonaios/anton/blob/main/routines/routines/scheduler/scheduler.py): job runner · Scheduled jobs, suspension, and timed orchestration · `routines/routines/scheduler/scheduler.py`

### Engine

Deterministic valuation package

- [Valuation Engine](https://github.com/antonaios/anton/blob/main/engine/valuation/__init__.py): python package · Deterministic spreadsheet-driven finance computation · `engine/valuation/__init__.py`
- [Template Registry](https://github.com/antonaios/anton/blob/main/engine/valuation/registry.py): cell mapping · Versioned template metadata and cell references · `engine/valuation/registry.py`
- [Excel Driver](https://github.com/antonaios/anton/blob/main/engine/valuation/excel_engine.py): spreadsheet executor · Applies workbook operations and runs model math · `engine/valuation/excel_engine.py`

### Vault

Canonical Markdown memory store

- [Markdown Vault](https://github.com/antonaios/anton/blob/HEAD/vault/Projects/_template/00%20Brief.md): obsidian repo · System of record for projects, notes, templates, and decisions · `vault/Projects/_template/00 Brief.md`
- [Templates](https://github.com/antonaios/anton/blob/main/vault/Templates/company.md): markdown templates · Reusable note and project templates · `vault/Templates/company.md`
- [Project Skeleton](https://github.com/antonaios/anton/blob/HEAD/vault/Projects/_template/01%20Source%20Register.md): project structure · Canonical deal workspace layout and registers · `vault/Projects/_template/01 Source Register.md`

## Connections

- Operator UI → API Client: calls · Client issues HTTP requests and receives state
- Operator UI → Workspace Panels: renders · UI assembles operator workspace from panels
- API Client → HTTP API: HTTP · Browser talks to backend control plane
- HTTP API → Route Layer: mounts · FastAPI exposes business capability routes
- HTTP API → Governance: wraps · Middleware enforces policy before execution
- Governance → Budgets: checks · Fails closed on spend and sensitivity limits
- Governance → Sessions: locks · Prevents conflicting operator actions
- Route Layer → Skills Runtime: dispatches · Governed routes invoke single skills
- Route Layer → Crew Flows: spawns · Routes can launch autonomous crew subprocesses
- Route Layer → Ingestion: runs · Routes trigger source capture and synthesis pipelines
- Route Layer → Recall: queries · Routes retrieve and rerank existing knowledge
- Route Layer → Vault Health: audits · Routes inspect vault freshness and integrity
- Route Layer → Vault Graph: inspects · Routes query relationships across the vault
- Route Layer → Scheduler: schedules · Routes create and manage background jobs
- Ingestion → Markdown Vault: writes · Approved outputs become governed markdown artifacts
- Recall → Markdown Vault: reads · Retrieval searches canonical memory
- Vault Health → Markdown Vault: checks · Health tools evaluate vault content
- Vault Graph → Markdown Vault: parses · Graph layer extracts structure from notes
- Skills Runtime → Valuation Engine: supplies inputs · Skills can hand off deterministic valuation work
- Valuation Engine → Template Registry: uses · Registry binds templates to cells and versions
- Valuation Engine → Excel Driver: executes · Excel driver performs the actual math and workbook writes
- Valuation Engine → Markdown Vault: exports · Results and artifacts can be stored back to memory
- Templates → Project Skeleton: defines · Template collection includes canonical project structure
- Markdown Vault → Templates: contains · Vault stores reusable note templates