# tuvl-io/tuvl architecture

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

- Interactive diagram: https://gitdiagram.com/tuvl-io/tuvl
- Repository: https://github.com/tuvl-io/tuvl

## Overview

tuvl is a YAML-declared workflow platform: users define contracts and agents, validate them, then serve and operate durable runs through APIs or the CLI. Insight adds a development UI and spec-driven authoring, review, and task workflows. The graph combines documented product stages with source-index-supported internal links; several capabilities are documented but their implementation files were not sampled, so those relationships are not asserted.

Main entry points: [`src/tuvl/runtime/host.py`](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/runtime/host.py) (Runtime Host), [`src/tuvl/core/app.py`](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/core/app.py) (Application Host), [`src/tuvl/contract/schema.py`](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/contract/schema.py) (Workflow Documents), [`src/tuvl/runtime/engines.py`](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/runtime/engines.py) (Engine Dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Authoring and Insight"]
  node_spec_work["Specs and Tasks<br/>[tasks.py]"]
  node_code_review["Code Review<br/>[review.py]"]
  node_insight_ui["Insight UI<br/>[App.tsx]"]
  node_insight_api["Insight Dev API<br/>[dev_core_router.py]"]
  node_audit["Audit Ledger<br/>[live.py]"]
end

subgraph group_contracts["Contracts and Configuration"]
  node_workflow_yaml["Workflow Documents<br/>[schema.py]"]
  node_contract_registry["Contract Registry<br/>[registry.py]"]
  node_project_config["Project Configuration<br/>[config.py]"]
  node_config_loader["Config Loader<br/>[config_loader.py]"]
  node_workflow_lint["Workflow Validation<br/>[engines.py]"]
end

subgraph group_execution["Workflow Execution"]
  node_runtime_host["Runtime Host<br/>[host.py]"]
  node_run_engine["Engine Dispatch<br/>[engines.py]"]
  node_run_journal["Run Journal<br/>[journal.py]"]
  node_storage["Blob Storage<br/>[store.py]"]
end

subgraph group_service["API and Operations"]
  node_app["Application Host<br/>[app.py]"]
  node_rest_api["REST and SSE<br/>[runs.py]"]
  node_mcp["MCP Export<br/>[mcp_export.py]"]
end

subgraph group_governance["Security and State"]
  node_datasources[("Database Sources<br/>[postgres.py]")]
  node_iam["Identity and Access<br/>[router.py]"]
end

node_developer(("Developer"))
node_workflow_user(("Workflow Caller"))
node_model_provider{{"Model Provider"}}

node_developer -->|"authors specs"| node_spec_work
node_developer -->|"uses dev UI"| node_insight_ui
node_spec_work -.->|"records activity"| node_audit
node_developer -->|"declares workflow"| node_workflow_yaml
node_workflow_yaml -->|"registers contracts"| node_contract_registry
node_config_loader -->|"registers documents"| node_contract_registry
node_config_loader -->|"reads settings"| node_project_config
node_workflow_yaml -->|"checked by"| node_workflow_lint
node_developer -->|"requests review"| node_code_review
node_insight_ui -.->|"calls dev API"| node_insight_api
node_app -->|"loads configuration"| node_config_loader
node_app -->|"starts runtime"| node_runtime_host
node_app -->|"mounts routes"| node_rest_api
node_app -->|"mounts auth"| node_iam
node_workflow_user -->|"submits run"| node_rest_api
node_rest_api -->|"dispatches run"| node_runtime_host
node_runtime_host -->|"dispatches agents"| node_run_engine
node_run_engine -->|"requests inference"| node_model_provider
node_runtime_host -->|"journals steps"| node_run_journal
node_runtime_host -.->|"uses transactions"| node_datasources
node_run_engine -.->|"uses declared tools"| node_storage
node_workflow_yaml -->|"exports enabled triggers"| node_mcp
node_iam -.->|"persists IAM state"| node_datasources

click node_spec_work "https://github.com/tuvl-io/tuvl/blob/main/insight/src/tuvl_insight/spec/tasks.py"
click node_code_review "https://github.com/tuvl-io/tuvl/blob/main/insight/src/tuvl_insight/cli/commands/review.py"
click node_insight_ui "https://github.com/tuvl-io/tuvl/blob/main/ui/src/App.tsx"
click node_insight_api "https://github.com/tuvl-io/tuvl/blob/main/insight/src/tuvl_insight/api/dev_core_router.py"
click node_audit "https://github.com/tuvl-io/tuvl/blob/main/insight/src/tuvl_insight/audit/live.py"
click node_workflow_yaml "https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/contract/schema.py"
click node_contract_registry "https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/contract/registry.py"
click node_project_config "https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/core/config.py"
click node_config_loader "https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/core/config_loader.py"
click node_workflow_lint "https://github.com/tuvl-io/tuvl/blob/main/insight/src/tuvl_insight/validate/workflow/engines.py"
click node_app "https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/core/app.py"
click node_rest_api "https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/api/runs.py"
click node_mcp "https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/api/mcp_export.py"
click node_runtime_host "https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/runtime/host.py"
click node_run_engine "https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/runtime/engines.py"
click node_run_journal "https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/runtime/journal.py"
click node_storage "https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/storage/store.py"
click node_datasources "https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/core/datasources/postgres.py"
click node_iam "https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/core/auth/router.py"

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_spec_work,node_code_review,node_insight_ui,node_insight_api,node_audit toneBlue
class node_workflow_yaml,node_contract_registry,node_project_config,node_config_loader,node_workflow_lint toneAmber
class node_runtime_host,node_run_engine,node_run_journal,node_storage toneMint
class node_app,node_rest_api,node_mcp toneRose
class node_datasources,node_iam,node_developer,node_workflow_user,node_model_provider toneIndigo
```

## Components

### Authoring and Insight

- [Specs and Tasks](https://github.com/tuvl-io/tuvl/blob/main/insight/src/tuvl_insight/spec/tasks.py): `insight/src/tuvl_insight/spec/tasks.py`
- [Code Review](https://github.com/tuvl-io/tuvl/blob/main/insight/src/tuvl_insight/cli/commands/review.py): `insight/src/tuvl_insight/cli/commands/review.py`
- [Insight UI](https://github.com/tuvl-io/tuvl/blob/main/ui/src/App.tsx): `ui/src/App.tsx`
- [Insight Dev API](https://github.com/tuvl-io/tuvl/blob/main/insight/src/tuvl_insight/api/dev_core_router.py): `insight/src/tuvl_insight/api/dev_core_router.py`
- [Audit Ledger](https://github.com/tuvl-io/tuvl/blob/main/insight/src/tuvl_insight/audit/live.py): `insight/src/tuvl_insight/audit/live.py`

### Contracts and Configuration

- [Workflow Documents](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/contract/schema.py): `src/tuvl/contract/schema.py`
- [Contract Registry](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/contract/registry.py): `src/tuvl/contract/registry.py`
- [Project Configuration](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/core/config.py): `src/tuvl/core/config.py`
- [Config Loader](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/core/config_loader.py): `src/tuvl/core/config_loader.py`
- [Workflow Validation](https://github.com/tuvl-io/tuvl/blob/main/insight/src/tuvl_insight/validate/workflow/engines.py): `insight/src/tuvl_insight/validate/workflow/engines.py`

### Workflow Execution

- [Runtime Host](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/runtime/host.py): `src/tuvl/runtime/host.py`
- [Engine Dispatch](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/runtime/engines.py): `src/tuvl/runtime/engines.py`
- [Run Journal](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/runtime/journal.py): `src/tuvl/runtime/journal.py`
- [Blob Storage](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/storage/store.py): `src/tuvl/storage/store.py`

### API and Operations

- [Application Host](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/core/app.py): `src/tuvl/core/app.py`
- [REST and SSE](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/api/runs.py): `src/tuvl/api/runs.py`
- [MCP Export](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/api/mcp_export.py): `src/tuvl/api/mcp_export.py`

### Security and State

- [Database Sources](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/core/datasources/postgres.py): `src/tuvl/core/datasources/postgres.py`
- [Identity and Access](https://github.com/tuvl-io/tuvl/blob/main/src/tuvl/core/auth/router.py): `src/tuvl/core/auth/router.py`

### Other components

- **Developer**
- **Workflow Caller**
- **Model Provider**

## Connections

- Developer → Specs and Tasks: authors specs (evidence: `README.md`)
- Developer → Insight UI: uses dev UI (evidence: `README.md`)
- Specs and Tasks → Audit Ledger: records activity (evidence: `insight/src/tuvl_insight/spec/tasks.py`)
- Developer → Workflow Documents: declares workflow (evidence: `README.md`)
- Workflow Documents → Contract Registry: registers contracts (evidence: `src/tuvl/contract/registry.py`)
- Config Loader → Contract Registry: registers documents (evidence: `src/tuvl/core/config_loader.py`)
- Config Loader → Project Configuration: reads settings (evidence: `src/tuvl/core/config_loader.py`)
- Workflow Documents → Workflow Validation: checked by (evidence: `README.md`)
- Developer → Code Review: requests review (evidence: `README.md`)
- Insight UI → Insight Dev API: calls dev API
- Application Host → Config Loader: loads configuration (evidence: `src/tuvl/core/app.py`)
- Application Host → Runtime Host: starts runtime (evidence: `src/tuvl/core/app.py`)
- Application Host → REST and SSE: mounts routes (evidence: `src/tuvl/core/app.py`)
- Application Host → Identity and Access: mounts auth (evidence: `src/tuvl/core/app.py`)
- Workflow Caller → REST and SSE: submits run (evidence: `README.md`)
- REST and SSE → Runtime Host: dispatches run (evidence: `README.md`)
- Runtime Host → Engine Dispatch: dispatches agents (evidence: `src/tuvl/runtime/engines.py`)
- Engine Dispatch → Model Provider: requests inference (evidence: `README.md`)
- Runtime Host → Run Journal: journals steps (evidence: `README.md`)
- Runtime Host → Database Sources: uses transactions
- Engine Dispatch → Blob Storage: uses declared tools
- Workflow Documents → MCP Export: exports enabled triggers (evidence: `README.md`)
- Identity and Access → Database Sources: persists IAM state (evidence: `src/tuvl/core/auth/router.py`)