# sifir-gun/contract-decision-graph architecture

> Architecture diagram of the GitHub repository sifir-gun/contract-decision-graph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sifir-gun/contract-decision-graph
- Repository: https://github.com/sifir-gun/contract-decision-graph

## Overview

Contract Decision Graph analyzes supplier-contract text and returns GO, GO_RESERVES, NO_GO, or ESCALADE with a justification and sealed audit record. The user workflow runs from the web interface through the contract service and LangGraph engine: validate input, extract and verify clauses, assess four domains, apply deterministic rules, route uncertainty to human review, explain, then seal. Corpus retrieval and local embeddings support assessment; PostgreSQL stores audit and resumable graph state. Major capabilities are taken from the README; unsampled subsystem internals and some adapter wiring are not asserted.

Main entry points: [`src/cdg/adapters/langgraph/orchestrator.py`](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/langgraph/orchestrator.py) (Graph orchestrator), [`src/cdg/application/nodes/decision_gate.py`](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/decision_gate.py) (Decision gate), [`src/cdg/adapters/web/app.py`](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/web/app.py) (Web interface), [`src/cdg/adapters/langgraph/engine.py`](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/langgraph/engine.py) (Graph engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_web["Web interface<br/>[app.py]"]
  node_service["Contract service<br/>[service.py]"]
end

subgraph group_workflow["Decision workflow"]
  node_engine["Graph engine<br/>[engine.py]"]
  node_orchestrator["Graph orchestrator<br/>[orchestrator.py]"]
  node_validate["Validate input<br/>[validate_input.py]"]
  node_extract["Extract clauses<br/>[extract_clauses.py]"]
  node_verify["Verify extraction"]
  node_analyst["Domain analysts<br/>[analyst.py]"]
  node_gate["Decision gate<br/>[decision_gate.py]"]
  node_review["Human review<br/>[reject.py]"]
  node_explain["Explanation<br/>[explain.py]"]
  node_seal["Audit sealing<br/>[audit_seal.py]"]
end

subgraph group_assessment["Assessment and corpus"]
  node_crag["CRAG retrieval<br/>[crag.py]"]
  node_corpus_ingest["Corpus ingestion<br/>[ingestion.py]"]
  node_corpus_model["Corpus model<br/>[corpus.py]"]
  node_retriever_port["Retriever port<br/>[retriever.py]"]
  node_rag_store[("Postgres RAG store<br/>[rag_store.py]")]
  node_embedder["Local embeddings<br/>[fastembed.py]"]
  node_llm_port["LLM port<br/>[llm.py]"]
end

subgraph group_domain["Rules and audit"]
  node_rules["Domain rules"]
  node_models["Decision models<br/>[models.py]"]
  node_config["Decision config<br/>[config.py]"]
  node_audit["Audit functions<br/>[audit.py]"]
end

subgraph group_adapters["Runtime adapters"]
  node_mistral["Mistral adapter<br/>[mistral.py]"]
  node_anthropic["Anthropic adapter<br/>[anthropic.py]"]
  node_audit_store[("Audit store adapter<br/>[audit_store.py]")]
  node_checkpointer[("Graph checkpointer<br/>[checkpointer.py]")]
  node_oidc["OIDC identity<br/>[oidc.py]"]
end

node_analyst_actor(("Analyst"))
node_reviewer_actor(("Human reviewer"))
node_postgres[("PostgreSQL")]

node_analyst_actor -->|"submits contract"| node_web
node_web -->|"calls actions"| node_service
node_service -->|"runs analysis"| node_engine
node_engine -->|"opens graph"| node_orchestrator
node_orchestrator -->|"routes to"| node_validate
node_orchestrator -->|"routes to"| node_extract
node_orchestrator -->|"routes to"| node_verify
node_orchestrator -->|"routes to"| node_analyst
node_orchestrator -->|"routes to"| node_gate
node_orchestrator -->|"routes to"| node_review
node_orchestrator -->|"routes to"| node_explain
node_orchestrator -->|"routes to"| node_seal
node_analyst -->|"assesses passages"| node_crag
node_crag -->|"searches corpus"| node_retriever_port
node_retriever_port -.->|"implemented by"| node_rag_store
node_rag_store -->|"embeds queries"| node_embedder
node_corpus_ingest -->|"builds chunks"| node_corpus_model
node_crag -->|"judges passages"| node_llm_port
node_llm_port -.->|"implemented by"| node_mistral
node_llm_port -.->|"alternative adapter"| node_anthropic
node_analyst -->|"applies rules"| node_rules
node_gate -->|"determines verdict"| node_rules
node_rules -->|"uses decision types"| node_models
node_gate -->|"interrupts for review"| node_reviewer_actor
node_review -->|"continues to"| node_explain
node_seal -->|"seals decision"| node_audit
node_audit -.->|"persists record"| node_audit_store
node_audit_store -.->|"writes audit log"| node_postgres
node_checkpointer -->|"stores checkpoints"| node_postgres
node_web -->|"verifies identity"| node_oidc
node_engine -->|"resumes threads"| node_checkpointer
node_gate -.->|"uses thresholds"| node_config

click node_web "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/web/app.py"
click node_service "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/service.py"
click node_engine "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/langgraph/engine.py"
click node_orchestrator "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/langgraph/orchestrator.py"
click node_validate "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/validate_input.py"
click node_extract "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/extract_clauses.py"
click node_verify "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/verify_extraction.py"
click node_analyst "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/analyst.py"
click node_gate "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/decision_gate.py"
click node_review "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/reject.py"
click node_explain "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/explain.py"
click node_seal "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/audit_seal.py"
click node_crag "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/crag.py"
click node_corpus_ingest "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/ingestion.py"
click node_corpus_model "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/domain/corpus.py"
click node_retriever_port "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/ports/retriever.py"
click node_rag_store "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/postgres/rag_store.py"
click node_embedder "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/fastembed.py"
click node_llm_port "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/ports/llm.py"
click node_mistral "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/llm/mistral.py"
click node_anthropic "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/llm/anthropic.py"
click node_rules "https://github.com/sifir-gun/contract-decision-graph/tree/main/src/cdg/domain/rules"
click node_models "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/domain/models.py"
click node_config "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/domain/config.py"
click node_audit "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/domain/audit.py"
click node_audit_store "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/postgres/audit_store.py"
click node_checkpointer "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/langgraph/checkpointer.py"
click node_oidc "https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/oidc.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_web,node_service,node_reviewer_actor toneBlue
class node_engine,node_orchestrator,node_validate,node_extract,node_verify,node_analyst,node_gate,node_review,node_explain,node_seal,node_postgres toneAmber
class node_crag,node_corpus_ingest,node_corpus_model,node_retriever_port,node_rag_store,node_embedder,node_llm_port toneMint
class node_rules,node_models,node_config,node_audit toneRose
class node_mistral,node_anthropic,node_audit_store,node_checkpointer,node_oidc,node_analyst_actor toneIndigo
```

## Components

### User entry

- [Web interface](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/web/app.py): `src/cdg/adapters/web/app.py`
- [Contract service](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/service.py): `src/cdg/application/service.py`

### Decision workflow

- [Graph engine](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/langgraph/engine.py): `src/cdg/adapters/langgraph/engine.py`
- [Graph orchestrator](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/langgraph/orchestrator.py): `src/cdg/adapters/langgraph/orchestrator.py`
- [Validate input](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/validate_input.py): `src/cdg/application/nodes/validate_input.py`
- [Extract clauses](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/extract_clauses.py): `src/cdg/application/nodes/extract_clauses.py`
- [Verify extraction](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/verify_extraction.py): `src/cdg/application/nodes/verify_extraction.py`
- [Domain analysts](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/analyst.py): `src/cdg/application/nodes/analyst.py`
- [Decision gate](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/decision_gate.py): `src/cdg/application/nodes/decision_gate.py`
- [Human review](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/reject.py): `src/cdg/application/nodes/reject.py`
- [Explanation](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/explain.py): `src/cdg/application/nodes/explain.py`
- [Audit sealing](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/nodes/audit_seal.py): `src/cdg/application/nodes/audit_seal.py`

### Assessment and corpus

- [CRAG retrieval](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/crag.py): `src/cdg/application/crag.py`
- [Corpus ingestion](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/application/ingestion.py): `src/cdg/application/ingestion.py`
- [Corpus model](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/domain/corpus.py): `src/cdg/domain/corpus.py`
- [Retriever port](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/ports/retriever.py): `src/cdg/ports/retriever.py`
- [Postgres RAG store](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/postgres/rag_store.py): `src/cdg/adapters/postgres/rag_store.py`
- [Local embeddings](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/fastembed.py): `src/cdg/adapters/fastembed.py`
- [LLM port](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/ports/llm.py): `src/cdg/ports/llm.py`

### Rules and audit

- [Domain rules](https://github.com/sifir-gun/contract-decision-graph/tree/main/src/cdg/domain/rules): `src/cdg/domain/rules`
- [Decision models](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/domain/models.py): `src/cdg/domain/models.py`
- [Decision config](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/domain/config.py): `src/cdg/domain/config.py`
- [Audit functions](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/domain/audit.py): `src/cdg/domain/audit.py`

### Runtime adapters

- [Mistral adapter](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/llm/mistral.py): `src/cdg/adapters/llm/mistral.py`
- [Anthropic adapter](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/llm/anthropic.py): `src/cdg/adapters/llm/anthropic.py`
- [Audit store adapter](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/postgres/audit_store.py): `src/cdg/adapters/postgres/audit_store.py`
- [Graph checkpointer](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/langgraph/checkpointer.py): `src/cdg/adapters/langgraph/checkpointer.py`
- [OIDC identity](https://github.com/sifir-gun/contract-decision-graph/blob/main/src/cdg/adapters/oidc.py): `src/cdg/adapters/oidc.py`

### Other components

- **Analyst**
- **Human reviewer**
- **PostgreSQL**

## Connections

- Analyst → Web interface: submits contract (evidence: `README.md`)
- Web interface → Contract service: calls actions (evidence: `src/cdg/adapters/web/app.py`)
- Contract service → Graph engine: runs analysis (evidence: `src/cdg/application/service.py`)
- Graph engine → Graph orchestrator: opens graph (evidence: `src/cdg/adapters/langgraph/engine.py`)
- Graph orchestrator → Validate input: routes to (evidence: `README.md`)
- Graph orchestrator → Extract clauses: routes to (evidence: `README.md`)
- Graph orchestrator → Verify extraction: routes to (evidence: `README.md`)
- Graph orchestrator → Domain analysts: routes to (evidence: `README.md`)
- Graph orchestrator → Decision gate: routes to (evidence: `README.md`)
- Graph orchestrator → Human review: routes to (evidence: `README.md`)
- Graph orchestrator → Explanation: routes to (evidence: `README.md`)
- Graph orchestrator → Audit sealing: routes to (evidence: `README.md`)
- Domain analysts → CRAG retrieval: assesses passages (evidence: `README.md`)
- CRAG retrieval → Retriever port: searches corpus (evidence: `src/cdg/application/crag.py`)
- Retriever port → Postgres RAG store: implemented by (evidence: `src/cdg/adapters/postgres/rag_store.py`)
- Postgres RAG store → Local embeddings: embeds queries (evidence: `src/cdg/adapters/postgres/rag_store.py`)
- Corpus ingestion → Corpus model: builds chunks (evidence: `src/cdg/application/ingestion.py`)
- CRAG retrieval → LLM port: judges passages (evidence: `src/cdg/application/crag.py`)
- LLM port → Mistral adapter: implemented by (evidence: `src/cdg/adapters/llm/mistral.py`)
- LLM port → Anthropic adapter: alternative adapter
- Domain analysts → Domain rules: applies rules (evidence: `README.md`)
- Decision gate → Domain rules: determines verdict (evidence: `README.md`)
- Domain rules → Decision models: uses decision types (evidence: `src/cdg/domain/rules/_common.py`)
- Decision gate → Human reviewer: interrupts for review (evidence: `README.md`)
- Human review → Explanation: continues to (evidence: `README.md`)
- Audit sealing → Audit functions: seals decision (evidence: `README.md`)
- Audit functions → Audit store adapter: persists record
- Audit store adapter → PostgreSQL: writes audit log
- Graph checkpointer → PostgreSQL: stores checkpoints (evidence: `src/cdg/adapters/langgraph/checkpointer.py`)
- Web interface → OIDC identity: verifies identity (evidence: `src/cdg/adapters/web/app.py`)
- Graph engine → Graph checkpointer: resumes threads (evidence: `src/cdg/adapters/langgraph/engine.py`)
- Decision gate → Decision config: uses thresholds
