# ambrose-tang/larch-verify architecture

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

- Interactive diagram: https://gitdiagram.com/ambrose-tang/larch-verify
- Repository: https://github.com/ambrose-tang/larch-verify

## Overview

Larch verifies functions by formalizing approved contracts as Lean models, checking proofs about those models, then comparing the real implementation against the model with generated tests and mutation analysis. The CLI and interactive session also support repository scanning, contract drafting, reports, and validated fix proposals. The graph combines documented workflow stages with relationships visible in the excerpts and SOURCE INDEX; unsampled subsystem links are omitted where their callers cannot be established.

Main entry points: [`larch/engine/session.py`](https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/session.py) (Run orchestration), [`larch/cli.py`](https://github.com/ambrose-tang/larch-verify/blob/master/larch/cli.py) (CLI), [`larch/lang.py`](https://github.com/ambrose-tang/larch-verify/blob/master/larch/lang.py) (Language dispatch), [`larch/chat.py`](https://github.com/ambrose-tang/larch-verify/blob/master/larch/chat.py) (Interactive drafting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User workflows"]
  node_cli["CLI<br/>[cli.py]"]
  node_chat["Interactive drafting<br/>[chat.py]"]
end

subgraph group_analysis["Repository and contracts"]
  node_repo["Repo discovery<br/>[repo.py]"]
  node_contracts["Contract parsing<br/>[contracts.py]"]
  node_language["Language dispatch<br/>[lang.py]"]
  node_pybackend["Python backend<br/>[backend.py]"]
  node_jsbackend["JS and TS backend<br/>[backend.py]"]
end

subgraph group_pipeline["Verification pipeline"]
  node_session["Run orchestration<br/>[session.py]"]
  node_formalize["Model formalization<br/>[formalize.py]"]
  node_spec["Formal specification<br/>[spec.py]"]
  node_prove["Proof workflow<br/>[prove.py]"]
  node_testing["Differential testing<br/>[runner.py]"]
  node_mutate["Mutation analysis<br/>[mutate.py]"]
  node_findings["Findings and fixes<br/>[findings.py]"]
  node_report["Results and reports<br/>[report.py]"]
end

subgraph group_runtime["Execution and Lean"]
  node_impl["Implementation adapter<br/>[impl_client.py]"]
  node_workspace["Lean workspace<br/>[workspace.py]"]
  node_toolchain["Lean toolchain<br/>[toolchain.py]"]
  node_checker["Proof checker<br/>[checker.py]"]
end

subgraph group_support["Models and services"]
  node_llm["LLM client and providers<br/>[providers.py]"]
  node_context["Run context<br/>[context.py]"]
  node_config["Run configuration<br/>[config.py]"]
  node_outputs["Certificates and outputs<br/>[outputs.py]"]
end

node_user(("Developer"))

node_user -->|"invokes"| node_cli
node_user -->|"starts session"| node_chat
node_cli -->|"runs verification"| node_session
node_chat -->|"drafts contracts"| node_contracts
node_cli -->|"scans candidates"| node_repo
node_cli -->|"loads contracts"| node_contracts
node_repo -->|"discovers functions"| node_language
node_language -->|"dispatches Python"| node_pybackend
node_language -->|"dispatches JS/TS"| node_jsbackend
node_session -->|"builds context"| node_context
node_session -->|"formalizes model"| node_formalize
node_formalize -->|"produces specification"| node_spec
node_session -->|"proves approved specs"| node_prove
node_session -->|"compares implementation"| node_testing
node_testing -->|"dispatches calls"| node_impl
node_session -->|"runs mutation analysis"| node_mutate
node_session -->|"records disagreements"| node_findings
node_session -->|"builds report"| node_report
node_session -->|"writes certificate"| node_outputs
node_prove -->|"checks proof"| node_checker
node_checker -->|"uses Lean toolchain"| node_toolchain
node_workspace -->|"runs Lean"| node_toolchain
node_context -->|"requests completion"| node_llm
node_session -->|"uses settings"| node_config

click node_cli "https://github.com/ambrose-tang/larch-verify/blob/master/larch/cli.py"
click node_chat "https://github.com/ambrose-tang/larch-verify/blob/master/larch/chat.py"
click node_repo "https://github.com/ambrose-tang/larch-verify/blob/master/larch/repo.py"
click node_contracts "https://github.com/ambrose-tang/larch-verify/blob/master/larch/contracts.py"
click node_language "https://github.com/ambrose-tang/larch-verify/blob/master/larch/lang.py"
click node_pybackend "https://github.com/ambrose-tang/larch-verify/blob/master/larch/py/backend.py"
click node_jsbackend "https://github.com/ambrose-tang/larch-verify/blob/master/larch/js/backend.py"
click node_session "https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/session.py"
click node_formalize "https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/formalize.py"
click node_spec "https://github.com/ambrose-tang/larch-verify/blob/master/larch/spec.py"
click node_prove "https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/prove.py"
click node_testing "https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/runner.py"
click node_mutate "https://github.com/ambrose-tang/larch-verify/blob/master/larch/py/mutate.py"
click node_findings "https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/findings.py"
click node_report "https://github.com/ambrose-tang/larch-verify/blob/master/larch/report.py"
click node_impl "https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/impl_client.py"
click node_workspace "https://github.com/ambrose-tang/larch-verify/blob/master/larch/lean/workspace.py"
click node_toolchain "https://github.com/ambrose-tang/larch-verify/blob/master/larch/lean/toolchain.py"
click node_checker "https://github.com/ambrose-tang/larch-verify/blob/master/larch/lean/checker.py"
click node_llm "https://github.com/ambrose-tang/larch-verify/blob/master/larch/llm/providers.py"
click node_context "https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/context.py"
click node_config "https://github.com/ambrose-tang/larch-verify/blob/master/larch/config.py"
click node_outputs "https://github.com/ambrose-tang/larch-verify/blob/master/larch/outputs.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_cli,node_chat toneBlue
class node_repo,node_contracts,node_language,node_pybackend,node_jsbackend toneAmber
class node_session,node_formalize,node_spec,node_prove,node_testing,node_mutate,node_findings,node_report toneMint
class node_impl,node_workspace,node_toolchain,node_checker toneRose
class node_llm,node_context,node_config,node_outputs,node_user toneIndigo
```

## Components

### User workflows

- [CLI](https://github.com/ambrose-tang/larch-verify/blob/master/larch/cli.py): `larch/cli.py`
- [Interactive drafting](https://github.com/ambrose-tang/larch-verify/blob/master/larch/chat.py): `larch/chat.py`

### Repository and contracts

- [Repo discovery](https://github.com/ambrose-tang/larch-verify/blob/master/larch/repo.py): `larch/repo.py`
- [Contract parsing](https://github.com/ambrose-tang/larch-verify/blob/master/larch/contracts.py): `larch/contracts.py`
- [Language dispatch](https://github.com/ambrose-tang/larch-verify/blob/master/larch/lang.py): `larch/lang.py`
- [Python backend](https://github.com/ambrose-tang/larch-verify/blob/master/larch/py/backend.py): `larch/py/backend.py`
- [JS and TS backend](https://github.com/ambrose-tang/larch-verify/blob/master/larch/js/backend.py): `larch/js/backend.py`

### Verification pipeline

- [Run orchestration](https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/session.py): `larch/engine/session.py`
- [Model formalization](https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/formalize.py): `larch/engine/formalize.py`
- [Formal specification](https://github.com/ambrose-tang/larch-verify/blob/master/larch/spec.py): `larch/spec.py`
- [Proof workflow](https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/prove.py): `larch/engine/prove.py`
- [Differential testing](https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/runner.py): `larch/engine/runner.py`
- [Mutation analysis](https://github.com/ambrose-tang/larch-verify/blob/master/larch/py/mutate.py): `larch/py/mutate.py`
- [Findings and fixes](https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/findings.py): `larch/engine/findings.py`
- [Results and reports](https://github.com/ambrose-tang/larch-verify/blob/master/larch/report.py): `larch/report.py`

### Execution and Lean

- [Implementation adapter](https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/impl_client.py): `larch/engine/impl_client.py`
- [Lean workspace](https://github.com/ambrose-tang/larch-verify/blob/master/larch/lean/workspace.py): `larch/lean/workspace.py`
- [Lean toolchain](https://github.com/ambrose-tang/larch-verify/blob/master/larch/lean/toolchain.py): `larch/lean/toolchain.py`
- [Proof checker](https://github.com/ambrose-tang/larch-verify/blob/master/larch/lean/checker.py): `larch/lean/checker.py`

### Models and services

- [LLM client and providers](https://github.com/ambrose-tang/larch-verify/blob/master/larch/llm/providers.py): `larch/llm/providers.py`
- [Run context](https://github.com/ambrose-tang/larch-verify/blob/master/larch/engine/context.py): `larch/engine/context.py`
- [Run configuration](https://github.com/ambrose-tang/larch-verify/blob/master/larch/config.py): `larch/config.py`
- [Certificates and outputs](https://github.com/ambrose-tang/larch-verify/blob/master/larch/outputs.py): `larch/outputs.py`

### Other components

- **Developer**

## Connections

- Developer → CLI: invokes
- Developer → Interactive drafting: starts session
- CLI → Run orchestration: runs verification (evidence: `larch/cli.py`)
- Interactive drafting → Contract parsing: drafts contracts (evidence: `larch/chat.py`)
- CLI → Repo discovery: scans candidates (evidence: `larch/cli.py`)
- CLI → Contract parsing: loads contracts (evidence: `larch/cli.py`)
- Repo discovery → Language dispatch: discovers functions (evidence: `larch/repo.py`)
- Language dispatch → Python backend: dispatches Python (evidence: `larch/lang.py`)
- Language dispatch → JS and TS backend: dispatches JS/TS (evidence: `larch/lang.py`)
- Run orchestration → Run context: builds context (evidence: `larch/engine/session.py`)
- Run orchestration → Model formalization: formalizes model (evidence: `larch/engine/session.py`)
- Model formalization → Formal specification: produces specification (evidence: `larch/engine/formalize.py`)
- Run orchestration → Proof workflow: proves approved specs (evidence: `larch/engine/session.py`)
- Run orchestration → Differential testing: compares implementation (evidence: `larch/engine/session.py`)
- Differential testing → Implementation adapter: dispatches calls (evidence: `larch/engine/runner.py`)
- Run orchestration → Mutation analysis: runs mutation analysis
- Run orchestration → Findings and fixes: records disagreements (evidence: `larch/engine/session.py`)
- Run orchestration → Results and reports: builds report (evidence: `larch/engine/session.py`)
- Run orchestration → Certificates and outputs: writes certificate
- Proof workflow → Proof checker: checks proof (evidence: `larch/engine/prove.py`)
- Proof checker → Lean toolchain: uses Lean toolchain (evidence: `larch/lean/checker.py`)
- Lean workspace → Lean toolchain: runs Lean (evidence: `larch/lean/workspace.py`)
- Run context → LLM client and providers: requests completion (evidence: `larch/engine/context.py`)
- Run orchestration → Run configuration: uses settings (evidence: `larch/engine/session.py`)
