# rajfirke/provena architecture

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

- Interactive diagram: https://gitdiagram.com/rajfirke/provena
- Repository: https://github.com/rajfirke/provena

## Overview

Provena governs agent context inputs: wrapped retrieval/tool calls are recorded, provenance and freshness are checked, policies can warn or block, and records form a tamper-evident chain for later verification and reporting. The graph preserves multi-agent aggregation, retention, CLI/MCP access, framework adapters, and telemetry. Core call edges are supported by the trail excerpt or README; some major subsystems are indexed or documented but their internal wiring was not sampled, so uncertain links are omitted.

Main entry points: [`src/provena/trail.py`](https://github.com/rajfirke/provena/blob/main/src/provena/trail.py) (Context trail), [`src/provena/cli/main.py`](https://github.com/rajfirke/provena/blob/main/src/provena/cli/main.py) (Command line), [`src/provena/exporters/otel.py`](https://github.com/rajfirke/provena/blob/main/src/provena/exporters/otel.py) (OpenTelemetry export), [`src/provena/report.py`](https://github.com/rajfirke/provena/blob/main/src/provena/report.py) (Compliance reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and validation"]
  node_trail["Context trail<br/>[trail.py]"]
  node_records["Context records<br/>[models.py]"]
  node_provenance["Provenance checks<br/>[provenance.py]"]
  node_freshness["Freshness checks<br/>[freshness.py]"]
  node_policy["Policy enforcement<br/>[policy.py]"]
end

subgraph group_audit["Audit and persistence"]
  node_hasher["Hash chain<br/>[hasher.py]"]
  node_storage[("SQLite and memory<br/>[storage.py]")]
  node_postgres[("PostgreSQL backend<br/>[storage_pg.py]")]
  node_buffer["Async buffer<br/>[buffer.py]"]
end

subgraph group_governance["Governance workflows"]
  node_report["Compliance reports<br/>[report.py]"]
  node_retention["Retention engine<br/>[retention.py]"]
  node_aggregate["Trail aggregation<br/>[aggregator.py]"]
end

subgraph group_interfaces["Access and integrations"]
  node_cli["Command line<br/>[main.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_adapters["Framework adapters"]
  node_otel["OpenTelemetry export<br/>[otel.py]"]
end

node_agent(("Agent or caller"))
node_otel_service(("OpenTelemetry"))

node_agent -->|"tracks input"| node_trail
node_trail -->|"creates entries"| node_records
node_trail -->|"validates provenance"| node_provenance
node_trail -->|"checks freshness"| node_freshness
node_trail -->|"evaluates policies"| node_policy
node_trail -->|"chains records"| node_hasher
node_trail -->|"persists records"| node_storage
node_trail -->|"uses backend"| node_postgres
node_trail -->|"buffers writes"| node_buffer
node_trail -->|"emits events"| node_otel
node_trail -->|"exports reports"| node_report
node_cli -->|"queries and verifies"| node_trail
node_cli -->|"runs retention"| node_retention
node_cli -->|"generates reports"| node_report
node_cli -->|"serves MCP"| node_mcp
node_agent -.->|"integrates framework"| node_adapters
node_aggregate -->|"aggregates trails"| node_trail
node_otel -->|"starts spans"| node_otel_service

click node_trail "https://github.com/rajfirke/provena/blob/main/src/provena/trail.py"
click node_records "https://github.com/rajfirke/provena/blob/main/src/provena/models.py"
click node_provenance "https://github.com/rajfirke/provena/blob/main/src/provena/validators/provenance.py"
click node_freshness "https://github.com/rajfirke/provena/blob/main/src/provena/validators/freshness.py"
click node_policy "https://github.com/rajfirke/provena/blob/main/src/provena/policy.py"
click node_hasher "https://github.com/rajfirke/provena/blob/main/src/provena/hasher.py"
click node_storage "https://github.com/rajfirke/provena/blob/main/src/provena/storage.py"
click node_postgres "https://github.com/rajfirke/provena/blob/main/src/provena/storage_pg.py"
click node_buffer "https://github.com/rajfirke/provena/blob/main/src/provena/buffer.py"
click node_report "https://github.com/rajfirke/provena/blob/main/src/provena/report.py"
click node_retention "https://github.com/rajfirke/provena/blob/main/src/provena/retention.py"
click node_aggregate "https://github.com/rajfirke/provena/blob/main/src/provena/aggregator.py"
click node_cli "https://github.com/rajfirke/provena/blob/main/src/provena/cli/main.py"
click node_mcp "https://github.com/rajfirke/provena/blob/main/src/provena/mcp_server.py"
click node_adapters "https://github.com/rajfirke/provena/tree/main/src/provena/integrations"
click node_otel "https://github.com/rajfirke/provena/blob/main/src/provena/exporters/otel.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_trail,node_records,node_provenance,node_freshness,node_policy toneBlue
class node_hasher,node_storage,node_postgres,node_buffer toneAmber
class node_report,node_retention,node_aggregate toneMint
class node_cli,node_mcp,node_adapters,node_otel toneRose
class node_agent,node_otel_service toneIndigo
```

## Components

### Capture and validation

- [Context trail](https://github.com/rajfirke/provena/blob/main/src/provena/trail.py): `src/provena/trail.py`
- [Context records](https://github.com/rajfirke/provena/blob/main/src/provena/models.py): `src/provena/models.py`
- [Provenance checks](https://github.com/rajfirke/provena/blob/main/src/provena/validators/provenance.py): `src/provena/validators/provenance.py`
- [Freshness checks](https://github.com/rajfirke/provena/blob/main/src/provena/validators/freshness.py): `src/provena/validators/freshness.py`
- [Policy enforcement](https://github.com/rajfirke/provena/blob/main/src/provena/policy.py): `src/provena/policy.py`

### Audit and persistence

- [Hash chain](https://github.com/rajfirke/provena/blob/main/src/provena/hasher.py): `src/provena/hasher.py`
- [SQLite and memory](https://github.com/rajfirke/provena/blob/main/src/provena/storage.py): `src/provena/storage.py`
- [PostgreSQL backend](https://github.com/rajfirke/provena/blob/main/src/provena/storage_pg.py): `src/provena/storage_pg.py`
- [Async buffer](https://github.com/rajfirke/provena/blob/main/src/provena/buffer.py): `src/provena/buffer.py`

### Governance workflows

- [Compliance reports](https://github.com/rajfirke/provena/blob/main/src/provena/report.py): `src/provena/report.py`
- [Retention engine](https://github.com/rajfirke/provena/blob/main/src/provena/retention.py): `src/provena/retention.py`
- [Trail aggregation](https://github.com/rajfirke/provena/blob/main/src/provena/aggregator.py): `src/provena/aggregator.py`

### Access and integrations

- [Command line](https://github.com/rajfirke/provena/blob/main/src/provena/cli/main.py): `src/provena/cli/main.py`
- [MCP server](https://github.com/rajfirke/provena/blob/main/src/provena/mcp_server.py): `src/provena/mcp_server.py`
- [Framework adapters](https://github.com/rajfirke/provena/tree/main/src/provena/integrations): `src/provena/integrations`
- [OpenTelemetry export](https://github.com/rajfirke/provena/blob/main/src/provena/exporters/otel.py): `src/provena/exporters/otel.py`

### Other components

- **Agent or caller**
- **OpenTelemetry**

## Connections

- Agent or caller → Context trail: tracks input (evidence: `README.md`)
- Context trail → Context records: creates entries (evidence: `src/provena/trail.py`)
- Context trail → Provenance checks: validates provenance (evidence: `src/provena/trail.py`)
- Context trail → Freshness checks: checks freshness (evidence: `src/provena/trail.py`)
- Context trail → Policy enforcement: evaluates policies (evidence: `src/provena/trail.py`)
- Context trail → Hash chain: chains records (evidence: `src/provena/trail.py`)
- Context trail → SQLite and memory: persists records (evidence: `src/provena/trail.py`)
- Context trail → PostgreSQL backend: uses backend (evidence: `src/provena/trail.py`)
- Context trail → Async buffer: buffers writes (evidence: `src/provena/trail.py`)
- Context trail → OpenTelemetry export: emits events (evidence: `src/provena/trail.py`)
- Context trail → Compliance reports: exports reports (evidence: `README.md`)
- Command line → Context trail: queries and verifies (evidence: `src/provena/cli/main.py`)
- Command line → Retention engine: runs retention (evidence: `src/provena/cli/main.py`)
- Command line → Compliance reports: generates reports (evidence: `src/provena/cli/main.py`)
- Command line → MCP server: serves MCP (evidence: `src/provena/cli/main.py`)
- Agent or caller → Framework adapters: integrates framework (evidence: `README.md`)
- Trail aggregation → Context trail: aggregates trails (evidence: `src/provena/aggregator.py`)
- OpenTelemetry export → OpenTelemetry: starts spans (evidence: `src/provena/exporters/otel.py`)