Architecture

The engine is a library first: plain TypeScript packages with typed inputs and outputs, and every door — CLI, HTTP API, MCP, Telegram, viewer — is a thin adapter over the job manager in packages/core.

flowchart TB
  subgraph Doors
    CLI[apps/cli]
    API[apps/server · Hono]
    MCP[apps/mcp]
    TG[apps/telegram · grammY]
    VIEW[apps/viewer · Vite+React]
  end
  subgraph Engine["packages/* (the engine)"]
    CORE[core · pipeline state machine, jobs, events]
    SCHEMA[schema · Zod contracts]
    INGEST[ingest]
    PROFILE[profile]
    METRICS[metrics]
    ANALYSIS[analysis]
    RETRIEVAL[retrieval]
    WEB[web]
    AGENT[agent]
    VERIFY[verify]
    REPORT[report]
    MODELS[models · ModelClient over AI SDK]
    STORE[store · DuckDB workspace]
  end
  CLI --> CORE
  API --> CORE
  MCP --> API
  TG --> API
  VIEW --> API
  CORE --> INGEST & PROFILE & METRICS & ANALYSIS & RETRIEVAL & WEB & AGENT & VERIFY & REPORT
  INGEST & PROFILE & METRICS & ANALYSIS & RETRIEVAL & VERIFY --> STORE
  AGENT & METRICS & WEB & VERIFY & RETRIEVAL --> MODELS

Packages and doors (docs/assets/diagrams/architecture.mmd)

Package	Does
schema	Zod contracts: report v1, metric YAML, config, events; JSON Schema export
store	One DuckDB workspace per job; migrations; typed queries
core	Pipeline state machine, checkpoints, event bus, job manager, follow-ups
ingest · profile	Files to tables and sections; profiling and data quality
metrics	Draft, validate, review and compile metric definitions
analysis	Measure, insight templates, decompositions, impact ranges, ranking
retrieval · web	Documents lane; sanitized web lane
models	ModelClient over the AI SDK; Ollama and OpenAI-compatible; FakeModel
agent	Fact sheet, quarantined extractor, explain, decide, ask, screening
verify	V1–V8 and the failure policy
report	report.json to self-contained HTML

More: docs/ARCHITECTURE.md.