# awaterma/phronesis architecture

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

- Interactive diagram: https://gitdiagram.com/awaterma/phronesis
- Repository: https://github.com/awaterma/phronesis
- Video tour (about a minute): https://gitdiagram.com/awaterma/phronesis/video

## Overview

Phronesis is a durable governance platform for LLM-assisted coding: host hooks evaluate on-disk rules at tool-call boundaries and return allow, warning, or block decisions. Its MCP server exposes management and inspection tools, while the RETE library provides the matching engine. Additional documented capabilities include durable context, temporal journey and lifecycle facts, confidence scoring, structural code graphs, drift analysis, and extensible predicates. The graph uses README relationships for product-level flows and sampled source references for engine internals; unsampled subsystem wiring is not asserted.

Main entry points: [`crates/phronesis-mcp/src/hook/mod.rs`](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/hook/mod.rs) (Action hooks), [`crates/phronesis/src/network.rs`](https://github.com/awaterma/phronesis/blob/main/crates/phronesis/src/network.rs) (RETE coordinator), [`crates/phronesis-mcp/src/server.rs`](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/server.rs) (MCP tools), [`crates/phronesis-mcp/src/graph/extract.rs`](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/graph/extract.rs) (Structural extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_governance["Governance loop"]
  node_hook["Action hooks<br/>[mod.rs]"]
  node_rulefiles["Rule files<br/>[rules_file.rs]"]
  node_rulelayers["Rule layers<br/>[rule_layers.rs]"]
  node_decision["Governance decision<br/>[mod.rs]"]
end

subgraph group_engine["RETE engine"]
  node_rete["RETE coordinator<br/>[network.rs]"]
  node_alpha["Alpha matching<br/>[alpha_network.rs]"]
  node_beta["Beta joins<br/>[beta_network.rs]"]
  node_agenda["Activation agenda<br/>[agenda.rs]"]
  node_production["Production states<br/>[production.rs]"]
  node_memory[("Working memory<br/>[wme.rs]")]
end

subgraph group_durable["Durable signals"]
  node_context["Durable context<br/>[context.rs]"]
  node_journey[("Journey facts<br/>[mod.rs]")]
  node_lifecycle["Lifecycle events<br/>[event.rs]"]
  node_confidence["Confidence signals<br/>[toolchain.rs]"]
end

subgraph group_analysis["Code analysis"]
  node_graphbuild["Structural extraction<br/>[extract.rs]"]
  node_graphstore[("Code graph state<br/>[store.rs]")]
  node_graphquery["Graph queries<br/>[query.rs]"]
  node_drift["Drift review<br/>[mod.rs]"]
  node_predicates["Predicate providers"]
end

subgraph group_interfaces["Interfaces"]
  node_mcp["MCP tools<br/>[server.rs]"]
  node_metrics["Metrics service<br/>[lib.rs]"]
end

node_host(("Agent host"))

node_host -->|"proposes action"| node_hook
node_hook -->|"reads rules"| node_rulefiles
node_hook -->|"evaluates rules"| node_rete
node_rete -->|"produces decision"| node_decision
node_decision -->|"allows warns blocks"| node_host
node_rulelayers -->|"resolves rules"| node_rulefiles
node_rete -->|"coordinates matching"| node_alpha
node_rete -->|"coordinates joins"| node_beta
node_rete -->|"schedules activations"| node_agenda
node_rete -->|"checks productions"| node_production
node_rete -->|"asserts facts"| node_memory
node_host -->|"receives guidance"| node_context
node_hook -->|"derives temporal facts"| node_journey
node_hook -->|"records lifecycle"| node_lifecycle
node_hook -->|"gathers outcomes"| node_confidence
node_hook -->|"derives event facts"| node_predicates
node_mcp -->|"serves inspection"| node_journey
node_mcp -->|"reports band"| node_confidence
node_mcp -->|"rebuilds graph"| node_graphbuild
node_graphbuild -->|"writes relations"| node_graphstore
node_mcp -->|"serves queries"| node_graphquery
node_graphquery -.->|"queries state"| node_graphstore
node_mcp -->|"serves review"| node_drift
node_metrics -->|"reads action logs"| node_hook

click node_hook "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/hook/mod.rs"
click node_rulefiles "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/rules_file.rs"
click node_rulelayers "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/rule_layers.rs"
click node_decision "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/hook/mod.rs"
click node_rete "https://github.com/awaterma/phronesis/blob/main/crates/phronesis/src/network.rs"
click node_alpha "https://github.com/awaterma/phronesis/blob/main/crates/phronesis/src/alpha_network.rs"
click node_beta "https://github.com/awaterma/phronesis/blob/main/crates/phronesis/src/beta_network.rs"
click node_agenda "https://github.com/awaterma/phronesis/blob/main/crates/phronesis/src/agenda.rs"
click node_production "https://github.com/awaterma/phronesis/blob/main/crates/phronesis/src/production.rs"
click node_memory "https://github.com/awaterma/phronesis/blob/main/crates/phronesis/src/wme.rs"
click node_context "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/context.rs"
click node_journey "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/journey/mod.rs"
click node_lifecycle "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/lifecycle/event.rs"
click node_confidence "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/outcomes/toolchain.rs"
click node_graphbuild "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/graph/extract.rs"
click node_graphstore "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/graph/store.rs"
click node_graphquery "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/graph/query.rs"
click node_drift "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/drift/mod.rs"
click node_predicates "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/predicate_provider.rs"
click node_mcp "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/server.rs"
click node_metrics "https://github.com/awaterma/phronesis/blob/main/crates/phronesis-metrics/src/lib.rs"

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_hook,node_rulefiles,node_rulelayers,node_decision toneBlue
class node_rete,node_alpha,node_beta,node_agenda,node_production,node_memory toneAmber
class node_context,node_journey,node_lifecycle,node_confidence toneMint
class node_graphbuild,node_graphstore,node_graphquery,node_drift,node_predicates toneRose
class node_mcp,node_metrics,node_host toneIndigo
```

## Components

### Governance loop

- [Action hooks](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/hook/mod.rs): `crates/phronesis-mcp/src/hook/mod.rs`
- [Rule files](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/rules_file.rs): `crates/phronesis-mcp/src/rules_file.rs`
- [Rule layers](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/rule_layers.rs): `crates/phronesis-mcp/src/rule_layers.rs`
- [Governance decision](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/hook/mod.rs): `crates/phronesis-mcp/src/hook/mod.rs`

### RETE engine

- [RETE coordinator](https://github.com/awaterma/phronesis/blob/main/crates/phronesis/src/network.rs): `crates/phronesis/src/network.rs`
- [Alpha matching](https://github.com/awaterma/phronesis/blob/main/crates/phronesis/src/alpha_network.rs): `crates/phronesis/src/alpha_network.rs`
- [Beta joins](https://github.com/awaterma/phronesis/blob/main/crates/phronesis/src/beta_network.rs): `crates/phronesis/src/beta_network.rs`
- [Activation agenda](https://github.com/awaterma/phronesis/blob/main/crates/phronesis/src/agenda.rs): `crates/phronesis/src/agenda.rs`
- [Production states](https://github.com/awaterma/phronesis/blob/main/crates/phronesis/src/production.rs): `crates/phronesis/src/production.rs`
- [Working memory](https://github.com/awaterma/phronesis/blob/main/crates/phronesis/src/wme.rs): `crates/phronesis/src/wme.rs`

### Durable signals

- [Durable context](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/context.rs): `crates/phronesis-mcp/src/context.rs`
- [Journey facts](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/journey/mod.rs): `crates/phronesis-mcp/src/journey/mod.rs`
- [Lifecycle events](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/lifecycle/event.rs): `crates/phronesis-mcp/src/lifecycle/event.rs`
- [Confidence signals](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/outcomes/toolchain.rs): `crates/phronesis-mcp/src/outcomes/toolchain.rs`

### Code analysis

- [Structural extraction](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/graph/extract.rs): `crates/phronesis-mcp/src/graph/extract.rs`
- [Code graph state](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/graph/store.rs): `crates/phronesis-mcp/src/graph/store.rs`
- [Graph queries](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/graph/query.rs): `crates/phronesis-mcp/src/graph/query.rs`
- [Drift review](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/drift/mod.rs): `crates/phronesis-mcp/src/drift/mod.rs`
- [Predicate providers](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/predicate_provider.rs): `crates/phronesis-mcp/src/predicate_provider.rs`

### Interfaces

- [MCP tools](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-mcp/src/server.rs): `crates/phronesis-mcp/src/server.rs`
- [Metrics service](https://github.com/awaterma/phronesis/blob/main/crates/phronesis-metrics/src/lib.rs): `crates/phronesis-metrics/src/lib.rs`

### Other components

- **Agent host**

## Connections

- Agent host → Action hooks: proposes action (evidence: `README.md`)
- Action hooks → Rule files: reads rules (evidence: `README.md`)
- Action hooks → RETE coordinator: evaluates rules (evidence: `README.md`)
- RETE coordinator → Governance decision: produces decision (evidence: `README.md`)
- Governance decision → Agent host: allows warns blocks (evidence: `README.md`)
- Rule layers → Rule files: resolves rules (evidence: `crates/phronesis-mcp/src/rule_layers.rs`)
- RETE coordinator → Alpha matching: coordinates matching (evidence: `crates/phronesis/src/network.rs`)
- RETE coordinator → Beta joins: coordinates joins (evidence: `crates/phronesis/src/network.rs`)
- RETE coordinator → Activation agenda: schedules activations (evidence: `crates/phronesis/src/network.rs`)
- RETE coordinator → Production states: checks productions (evidence: `crates/phronesis/src/network.rs`)
- RETE coordinator → Working memory: asserts facts (evidence: `crates/phronesis/src/network.rs`)
- Agent host → Durable context: receives guidance (evidence: `README.md`)
- Action hooks → Journey facts: derives temporal facts (evidence: `README.md`)
- Action hooks → Lifecycle events: records lifecycle (evidence: `README.md`)
- Action hooks → Confidence signals: gathers outcomes (evidence: `README.md`)
- Action hooks → Predicate providers: derives event facts (evidence: `README.md`)
- MCP tools → Journey facts: serves inspection (evidence: `README.md`)
- MCP tools → Confidence signals: reports band (evidence: `README.md`)
- MCP tools → Structural extraction: rebuilds graph (evidence: `README.md`)
- Structural extraction → Code graph state: writes relations (evidence: `README.md`)
- MCP tools → Graph queries: serves queries (evidence: `README.md`)
- Graph queries → Code graph state: queries state
- MCP tools → Drift review: serves review (evidence: `README.md`)
- Metrics service → Action hooks: reads action logs