# redmaplewww/evkg architecture

> Architecture diagram of the GitHub repository redmaplewww/evkg, 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/redmaplewww/evkg
- Repository: https://github.com/redmaplewww/evkg

## Overview

evkg is a domain-configurable evidence knowledge graph with a CLI and Web workbench. Its main workflow takes source material through ingestion, claim/entity extraction, automated quality attacks, evidence dossiers, and indexed or graph-based exploration. The graph preserves the documented attack mechanisms and Web capabilities; edges reflect README statements or references in the provided SOURCE INDEX. Some detailed runtime wiring is unsampled, so uncertain links are omitted.

Main entry points: [`src/evkg/attack/__init__.py`](https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/__init__.py) (Attack Orchestrator), [`src/evkg/cli.py`](https://github.com/redmaplewww/evkg/blob/main/src/evkg/cli.py) (CLI Commands), [`src/evkg/store.py`](https://github.com/redmaplewww/evkg/blob/main/src/evkg/store.py) (Knowledge Store), [`src/evkg/web.py`](https://github.com/redmaplewww/evkg/blob/main/src/evkg/web.py) (Web API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion"]
  node_pipeline["Ingestion Pipeline<br/>[pipeline.py]"]
  node_readers["Source Readers<br/>[connectors.py]"]
  node_wiki["Wiki Import<br/>[wikitext.py]"]
  node_providers["Ingestion Providers<br/>[providers.py]"]
end

subgraph group_knowledge["Graph Construction"]
  node_extract["Claim Extraction<br/>[extract.py]"]
  node_resolution["Entity Resolution"]
end

subgraph group_quality["Evidence Quality"]
  node_attackrun["Attack Orchestrator<br/>[__init__.py]"]
  node_verify["Claim Verifier<br/>[verifier.py]"]
  node_contradiction["Contradiction Scan<br/>[contradiction.py]"]
  node_deterministic["Rule Conflict Scan<br/>[deterministic.py]"]
  node_adversarial["Red-Team Review<br/>[adversarial.py]"]
  node_auditor["Invariant Audit<br/>[auditor.py]"]
  node_damage["Audit Fault Test<br/>[damage.py]"]
end

subgraph group_access["Search &amp; Workbench"]
  node_cli["CLI Commands<br/>[cli.py]"]
  node_dossier["Evidence Dossier<br/>[dossier.py]"]
  node_search["Unified Search<br/>[search.py]"]
  node_fts[("Full-Text Index<br/>[fts.py]")]
  node_web["Web API<br/>[web.py]"]
  node_frontend["Web Workbench<br/>[main.jsx]"]
end

subgraph group_foundation["Shared Foundations"]
  node_domain["Graph Data Models<br/>[domain.py]"]
  node_profile["Domain Profile<br/>[config.py]"]
  node_store[("Knowledge Store<br/>[store.py]")]
  node_model["Model Gateway<br/>[model_gateway.py]"]
end

node_user(("User"))
node_modelservice["LLM Provider"]

node_user -->|"runs commands"| node_cli
node_user -->|"uses workbench"| node_frontend
node_cli -->|"dispatches ingest"| node_pipeline
node_pipeline -->|"selects reader"| node_readers
node_pipeline -->|"uses providers"| node_providers
node_readers -->|"uses wiki reader"| node_wiki
node_pipeline -->|"saves assets"| node_store
node_cli -->|"dispatches extract"| node_extract
node_extract -->|"reads and writes"| node_store
node_extract -->|"resolves entities"| node_resolution
node_extract -->|"requests extraction"| node_model
node_extract -->|"uses profile"| node_profile
node_model -->|"sends model requests"| node_modelservice
node_cli -->|"dispatches attack"| node_attackrun
node_attackrun -->|"runs verifier"| node_verify
node_attackrun -->|"runs scan"| node_contradiction
node_attackrun -->|"runs scan"| node_deterministic
node_attackrun -->|"runs red team"| node_adversarial
node_attackrun -->|"runs audit"| node_auditor
node_attackrun -->|"runs fault test"| node_damage
node_verify -->|"requests review"| node_model
node_verify -->|"reads and updates"| node_store
node_contradiction -->|"requests scan"| node_model
node_adversarial -->|"requests review"| node_model
node_auditor -->|"audits records"| node_store
node_damage -->|"checks detection"| node_auditor
node_cli -->|"dispatches dossier"| node_dossier
node_dossier -->|"reads evidence"| node_store
node_cli -->|"dispatches search"| node_search
node_search -->|"matches passages"| node_fts
node_search -->|"queries records"| node_store
node_fts -->|"indexes passages"| node_store
node_cli -->|"starts service"| node_web
node_frontend -->|"calls API"| node_web
node_web -->|"uses search"| node_search
node_web -->|"generates dossiers"| node_dossier
node_web -->|"uses attack reports"| node_attackrun
node_web -->|"queries graph data"| node_store

click node_cli "https://github.com/redmaplewww/evkg/blob/main/src/evkg/cli.py"
click node_pipeline "https://github.com/redmaplewww/evkg/blob/main/src/evkg/ingest/pipeline.py"
click node_readers "https://github.com/redmaplewww/evkg/blob/main/src/evkg/ingest/connectors.py"
click node_wiki "https://github.com/redmaplewww/evkg/blob/main/src/evkg/ingest/wikitext.py"
click node_providers "https://github.com/redmaplewww/evkg/blob/main/src/evkg/ingest/providers.py"
click node_extract "https://github.com/redmaplewww/evkg/blob/main/src/evkg/extract.py"
click node_resolution "https://github.com/redmaplewww/evkg/blob/main/src/evkg/entity_resolution.py"
click node_domain "https://github.com/redmaplewww/evkg/blob/main/src/evkg/domain.py"
click node_profile "https://github.com/redmaplewww/evkg/blob/main/src/evkg/config.py"
click node_store "https://github.com/redmaplewww/evkg/blob/main/src/evkg/store.py"
click node_model "https://github.com/redmaplewww/evkg/blob/main/src/evkg/model_gateway.py"
click node_attackrun "https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/__init__.py"
click node_verify "https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/verifier.py"
click node_contradiction "https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/contradiction.py"
click node_deterministic "https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/deterministic.py"
click node_adversarial "https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/adversarial.py"
click node_auditor "https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/auditor.py"
click node_damage "https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/damage.py"
click node_dossier "https://github.com/redmaplewww/evkg/blob/main/src/evkg/evidence/dossier.py"
click node_search "https://github.com/redmaplewww/evkg/blob/main/src/evkg/index/search.py"
click node_fts "https://github.com/redmaplewww/evkg/blob/main/src/evkg/index/fts.py"
click node_web "https://github.com/redmaplewww/evkg/blob/main/src/evkg/web.py"
click node_frontend "https://github.com/redmaplewww/evkg/blob/main/frontend/src/main.jsx"

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_pipeline,node_readers,node_wiki,node_providers,node_user toneBlue
class node_extract,node_resolution toneAmber
class node_attackrun,node_verify,node_contradiction,node_deterministic,node_adversarial,node_auditor,node_damage toneMint
class node_cli,node_dossier,node_search,node_fts,node_web,node_frontend toneRose
class node_domain,node_profile,node_store,node_model,node_modelservice toneIndigo
```

## Components

### Ingestion

- [Ingestion Pipeline](https://github.com/redmaplewww/evkg/blob/main/src/evkg/ingest/pipeline.py): `src/evkg/ingest/pipeline.py`
- [Source Readers](https://github.com/redmaplewww/evkg/blob/main/src/evkg/ingest/connectors.py): `src/evkg/ingest/connectors.py`
- [Wiki Import](https://github.com/redmaplewww/evkg/blob/main/src/evkg/ingest/wikitext.py): `src/evkg/ingest/wikitext.py`
- [Ingestion Providers](https://github.com/redmaplewww/evkg/blob/main/src/evkg/ingest/providers.py): `src/evkg/ingest/providers.py`

### Graph Construction

- [Claim Extraction](https://github.com/redmaplewww/evkg/blob/main/src/evkg/extract.py): `src/evkg/extract.py`
- [Entity Resolution](https://github.com/redmaplewww/evkg/blob/main/src/evkg/entity_resolution.py): `src/evkg/entity_resolution.py`

### Evidence Quality

- [Attack Orchestrator](https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/__init__.py): `src/evkg/attack/__init__.py`
- [Claim Verifier](https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/verifier.py): `src/evkg/attack/verifier.py`
- [Contradiction Scan](https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/contradiction.py): `src/evkg/attack/contradiction.py`
- [Rule Conflict Scan](https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/deterministic.py): `src/evkg/attack/deterministic.py`
- [Red-Team Review](https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/adversarial.py): `src/evkg/attack/adversarial.py`
- [Invariant Audit](https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/auditor.py): `src/evkg/attack/auditor.py`
- [Audit Fault Test](https://github.com/redmaplewww/evkg/blob/main/src/evkg/attack/damage.py): `src/evkg/attack/damage.py`

### Search & Workbench

- [CLI Commands](https://github.com/redmaplewww/evkg/blob/main/src/evkg/cli.py): `src/evkg/cli.py`
- [Evidence Dossier](https://github.com/redmaplewww/evkg/blob/main/src/evkg/evidence/dossier.py): `src/evkg/evidence/dossier.py`
- [Unified Search](https://github.com/redmaplewww/evkg/blob/main/src/evkg/index/search.py): `src/evkg/index/search.py`
- [Full-Text Index](https://github.com/redmaplewww/evkg/blob/main/src/evkg/index/fts.py): `src/evkg/index/fts.py`
- [Web API](https://github.com/redmaplewww/evkg/blob/main/src/evkg/web.py): `src/evkg/web.py`
- [Web Workbench](https://github.com/redmaplewww/evkg/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`

### Shared Foundations

- [Graph Data Models](https://github.com/redmaplewww/evkg/blob/main/src/evkg/domain.py): `src/evkg/domain.py`
- [Domain Profile](https://github.com/redmaplewww/evkg/blob/main/src/evkg/config.py): `src/evkg/config.py`
- [Knowledge Store](https://github.com/redmaplewww/evkg/blob/main/src/evkg/store.py): `src/evkg/store.py`
- [Model Gateway](https://github.com/redmaplewww/evkg/blob/main/src/evkg/model_gateway.py): `src/evkg/model_gateway.py`

### Other components

- **User**
- **LLM Provider**

## Connections

- User → CLI Commands: runs commands (evidence: `README.md`)
- User → Web Workbench: uses workbench (evidence: `README.md`)
- CLI Commands → Ingestion Pipeline: dispatches ingest (evidence: `src/evkg/cli.py`)
- Ingestion Pipeline → Source Readers: selects reader (evidence: `src/evkg/ingest/pipeline.py`)
- Ingestion Pipeline → Ingestion Providers: uses providers (evidence: `src/evkg/ingest/pipeline.py`)
- Source Readers → Wiki Import: uses wiki reader (evidence: `src/evkg/ingest/connectors.py`)
- Ingestion Pipeline → Knowledge Store: saves assets (evidence: `src/evkg/ingest/pipeline.py`)
- CLI Commands → Claim Extraction: dispatches extract (evidence: `src/evkg/cli.py`)
- Claim Extraction → Knowledge Store: reads and writes (evidence: `src/evkg/extract.py`)
- Claim Extraction → Entity Resolution: resolves entities (evidence: `src/evkg/extract.py`)
- Claim Extraction → Model Gateway: requests extraction (evidence: `src/evkg/extract.py`)
- Claim Extraction → Domain Profile: uses profile (evidence: `src/evkg/extract.py`)
- Model Gateway → LLM Provider: sends model requests (evidence: `src/evkg/model_gateway.py`)
- CLI Commands → Attack Orchestrator: dispatches attack (evidence: `src/evkg/cli.py`)
- Attack Orchestrator → Claim Verifier: runs verifier (evidence: `src/evkg/attack/__init__.py`)
- Attack Orchestrator → Contradiction Scan: runs scan (evidence: `src/evkg/attack/__init__.py`)
- Attack Orchestrator → Rule Conflict Scan: runs scan (evidence: `src/evkg/attack/__init__.py`)
- Attack Orchestrator → Red-Team Review: runs red team (evidence: `src/evkg/attack/__init__.py`)
- Attack Orchestrator → Invariant Audit: runs audit (evidence: `src/evkg/attack/__init__.py`)
- Attack Orchestrator → Audit Fault Test: runs fault test (evidence: `src/evkg/attack/__init__.py`)
- Claim Verifier → Model Gateway: requests review (evidence: `src/evkg/attack/verifier.py`)
- Claim Verifier → Knowledge Store: reads and updates (evidence: `src/evkg/attack/verifier.py`)
- Contradiction Scan → Model Gateway: requests scan (evidence: `src/evkg/attack/contradiction.py`)
- Red-Team Review → Model Gateway: requests review (evidence: `src/evkg/attack/adversarial.py`)
- Invariant Audit → Knowledge Store: audits records (evidence: `src/evkg/attack/auditor.py`)
- Audit Fault Test → Invariant Audit: checks detection (evidence: `src/evkg/attack/damage.py`)
- CLI Commands → Evidence Dossier: dispatches dossier (evidence: `src/evkg/cli.py`)
- Evidence Dossier → Knowledge Store: reads evidence (evidence: `src/evkg/evidence/dossier.py`)
- CLI Commands → Unified Search: dispatches search (evidence: `src/evkg/cli.py`)
- Unified Search → Full-Text Index: matches passages (evidence: `src/evkg/index/search.py`)
- Unified Search → Knowledge Store: queries records (evidence: `src/evkg/index/search.py`)
- Full-Text Index → Knowledge Store: indexes passages (evidence: `src/evkg/index/fts.py`)
- CLI Commands → Web API: starts service (evidence: `src/evkg/cli.py`)
- Web Workbench → Web API: calls API (evidence: `README.md`)
- Web API → Unified Search: uses search (evidence: `src/evkg/web.py`)
- Web API → Evidence Dossier: generates dossiers (evidence: `src/evkg/web.py`)
- Web API → Attack Orchestrator: uses attack reports (evidence: `src/evkg/web.py`)
- Web API → Knowledge Store: queries graph data (evidence: `src/evkg/web.py`)