# simonbouhier/epp_verdict architecture

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

- Interactive diagram: https://gitdiagram.com/simonbouhier/epp_verdict
- Repository: https://github.com/simonbouhier/epp_verdict

## Overview

EPP combines multi-model deliberation and evidence-backed attestations with a read-only dashboard for historical runs. The principal workflow explores a claim, aggregates extracted triplets into consensus, crystallizes results as attestations, and stores them. Separate branches cover deterministic source anchoring, contract auditing, and governance; blockchain publication is retired, though an on-chain archive and Solana client remain. The excerpts document the ESMM pipeline and some storage and provider behavior; links between unsampled API, audit, and governance modules are therefore kept conservative.

Main entry points: [`services/esmm/pipeline.py`](https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/pipeline.py) (ESMM pipeline), [`database/engine.py`](https://github.com/simonbouhier/epp_verdict/blob/main/database/engine.py) (EPP database), [`services/esmm/orchestrator.py`](https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/orchestrator.py) (Run orchestrator), [`services/esmm/cycle_manager.py`](https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/cycle_manager.py) (Exploration cycles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deliberation["Deliberation"]
  node_esmm["ESMM pipeline<br/>[pipeline.py]"]
  node_orchestrator["Run orchestrator<br/>[orchestrator.py]"]
  node_cycles["Exploration cycles<br/>[cycle_manager.py]"]
  node_rotator["Model rotation<br/>[model_rotator.py]"]
  node_providers["Model providers"]
  node_consensus["Triplet consensus"]
end

subgraph group_evidence["Evidence and storage"]
  node_attestation["Attestation pipeline<br/>[pipeline.py]"]
  node_source_adapters["Source adapters"]
  node_database[("EPP database<br/>[engine.py]")]
end

subgraph group_interfaces["Interfaces and archive"]
  node_api["API routes"]
  node_dashboard["Historical dashboard<br/>[App.tsx]"]
  node_routes["Archive pages"]
  node_loader["Run data loader<br/>[loader.ts]"]
end

subgraph group_integrations["Auditing and integrations"]
  node_audit["Contract auditing"]
  node_governance["Governance proposals<br/>[proposal.py]"]
  node_solana["Solana client<br/>[client.py]"]
end

node_user(("Claim submitter"))
node_model_service(("Model service"))
node_sqlite[("SQLite")]
node_chain[("Solana devnet")]
node_archive[("Historical run data")]

node_user -->|"submits claims"| node_api
node_api -->|"dispatches runs"| node_esmm
node_esmm -->|"starts run"| node_orchestrator
node_orchestrator -->|"manages cycles"| node_cycles
node_cycles -->|"requests model responses"| node_rotator
node_rotator -->|"selects provider"| node_providers
node_providers -.->|"requests inference"| node_model_service
node_orchestrator -->|"aggregates triplets"| node_consensus
node_esmm -->|"fetches source evidence"| node_source_adapters
node_esmm -->|"crystallizes results"| node_attestation
node_attestation -->|"stores attestations"| node_database
node_database -->|"reads and writes"| node_sqlite
node_audit -.->|"uses stored data"| node_database
node_governance -.->|"uses stored data"| node_database
node_solana -.->|"submits and queries"| node_chain
node_dashboard -->|"routes visitors"| node_routes
node_routes -->|"loads archive data"| node_loader
node_loader -->|"reads historical runs"| node_archive

click node_api "https://github.com/simonbouhier/epp_verdict/tree/main/app/api"
click node_esmm "https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/pipeline.py"
click node_orchestrator "https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/orchestrator.py"
click node_cycles "https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/cycle_manager.py"
click node_rotator "https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/model_rotator.py"
click node_providers "https://github.com/simonbouhier/epp_verdict/tree/main/services/providers"
click node_consensus "https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/consensus_engine.py"
click node_attestation "https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/pipeline.py"
click node_source_adapters "https://github.com/simonbouhier/epp_verdict/tree/main/services/sources/adapters"
click node_database "https://github.com/simonbouhier/epp_verdict/blob/main/database/engine.py"
click node_audit "https://github.com/simonbouhier/epp_verdict/tree/main/services/audit"
click node_governance "https://github.com/simonbouhier/epp_verdict/blob/main/services/governance/proposal.py"
click node_solana "https://github.com/simonbouhier/epp_verdict/blob/main/services/solana/client.py"
click node_dashboard "https://github.com/simonbouhier/epp_verdict/blob/main/ui/src/App.tsx"
click node_routes "https://github.com/simonbouhier/epp_verdict/tree/main/ui/src/routes"
click node_loader "https://github.com/simonbouhier/epp_verdict/blob/main/ui/src/data/loader.ts"

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_esmm,node_orchestrator,node_cycles,node_rotator,node_providers,node_consensus toneBlue
class node_attestation,node_source_adapters,node_database,node_sqlite,node_chain,node_archive toneAmber
class node_api,node_dashboard,node_routes,node_loader toneMint
class node_audit,node_governance,node_solana toneRose
class node_user,node_model_service toneIndigo
```

## Components

### Deliberation

- [ESMM pipeline](https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/pipeline.py): `services/esmm/pipeline.py`
- [Run orchestrator](https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/orchestrator.py): `services/esmm/orchestrator.py`
- [Exploration cycles](https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/cycle_manager.py): `services/esmm/cycle_manager.py`
- [Model rotation](https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/model_rotator.py): `services/esmm/model_rotator.py`
- [Model providers](https://github.com/simonbouhier/epp_verdict/tree/main/services/providers): `services/providers`
- [Triplet consensus](https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/consensus_engine.py): `services/esmm/consensus_engine.py`

### Evidence and storage

- [Attestation pipeline](https://github.com/simonbouhier/epp_verdict/blob/main/services/esmm/pipeline.py): `services/esmm/pipeline.py`
- [Source adapters](https://github.com/simonbouhier/epp_verdict/tree/main/services/sources/adapters): `services/sources/adapters`
- [EPP database](https://github.com/simonbouhier/epp_verdict/blob/main/database/engine.py): `database/engine.py`

### Interfaces and archive

- [API routes](https://github.com/simonbouhier/epp_verdict/tree/main/app/api): `app/api`
- [Historical dashboard](https://github.com/simonbouhier/epp_verdict/blob/main/ui/src/App.tsx): `ui/src/App.tsx`
- [Archive pages](https://github.com/simonbouhier/epp_verdict/tree/main/ui/src/routes): `ui/src/routes`
- [Run data loader](https://github.com/simonbouhier/epp_verdict/blob/main/ui/src/data/loader.ts): `ui/src/data/loader.ts`

### Auditing and integrations

- [Contract auditing](https://github.com/simonbouhier/epp_verdict/tree/main/services/audit): `services/audit`
- [Governance proposals](https://github.com/simonbouhier/epp_verdict/blob/main/services/governance/proposal.py): `services/governance/proposal.py`
- [Solana client](https://github.com/simonbouhier/epp_verdict/blob/main/services/solana/client.py): `services/solana/client.py`

### Other components

- **Claim submitter**
- **Model service**
- **SQLite**
- **Solana devnet**
- **Historical run data**

## Connections

- Claim submitter → API routes: submits claims
- API routes → ESMM pipeline: dispatches runs
- ESMM pipeline → Run orchestrator: starts run
- Run orchestrator → Exploration cycles: manages cycles
- Exploration cycles → Model rotation: requests model responses
- Model rotation → Model providers: selects provider
- Model providers → Model service: requests inference
- Run orchestrator → Triplet consensus: aggregates triplets
- ESMM pipeline → Source adapters: fetches source evidence
- ESMM pipeline → Attestation pipeline: crystallizes results
- Attestation pipeline → EPP database: stores attestations
- EPP database → SQLite: reads and writes
- Contract auditing → EPP database: uses stored data
- Governance proposals → EPP database: uses stored data
- Solana client → Solana devnet: submits and queries
- Historical dashboard → Archive pages: routes visitors
- Archive pages → Run data loader: loads archive data
- Run data loader → Historical run data: reads historical runs