# amilheir/wikigraph architecture

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

## Overview

WikiGraph is a self-growing Wikipedia GraphRAG chatbot. A browser submits a question to the Flask WSGI API, which queues it in IRIS; the polling service dispatches it to the chat orchestrator. Retrieval searches the graph and scoped vectors first, and a weak match can trigger one-page Wikipedia lookup, article ingestion and LLM extraction before grounded answer generation. The README also documents add-by-title, approval, graph cleanup, management and documentation capabilities. Edges reflect cited excerpts or README statements; some operation internals and UI/API details are unsampled.

Main entry points: [`src-iris/production/processes.py`](https://github.com/amilheir/wikigraph/blob/main/src-iris/production/processes.py) (Chat orchestrator), [`src-iris/wsgi/static/wg_check.js`](https://github.com/amilheir/wikigraph/blob/main/src-iris/wsgi/static/wg_check.js) (Chat UI), [`src-iris/wsgi/app.py`](https://github.com/amilheir/wikigraph/blob/main/src-iris/wsgi/app.py) (Flask API), [`src-iris/production/operations.py`](https://github.com/amilheir/wikigraph/blob/main/src-iris/production/operations.py) (LLM operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Chat interface"]
  node_frontend["Chat UI<br/>[wg_check.js]"]
  node_docs["Product documentation<br/>[overview.html]"]
end

subgraph group_api["Web API"]
  node_wsgi["Flask API<br/>[app.py]"]
end

subgraph group_workflow["Interop workflow"]
  node_poller["Polling service<br/>[services.py]"]
  node_chatprocess["Chat orchestrator<br/>[processes.py]"]
  node_messages["Interop messages<br/>[messages.py]"]
end

subgraph group_knowledge["Knowledge pipeline"]
  node_knowledge["Graph retrieval<br/>[operations.py]"]
  node_wikipedia["Wikipedia lookup<br/>[operations.py]"]
  node_ingest["Article ingestion<br/>[processes.py]"]
  node_llm["LLM operations<br/>[operations.py]"]
  node_resolution["Entity resolution<br/>[operations.py]"]
  node_helpers["Chunking and helpers<br/>[common.py]"]
end

subgraph group_state["IRIS state and models"]
  node_chatrow[("Chat request queue")]
  node_graphdb[("GraphKB storage")]
end

node_browser(("Chat user"))
node_ollama["Ollama models"]
node_wiki["Wikipedia"]

node_browser -->|"uses"| node_frontend
node_frontend -->|"submits and polls"| node_wsgi
node_wsgi -->|"queues request"| node_chatrow
node_poller -->|"claims queued rows"| node_chatrow
node_poller -->|"dispatches chat"| node_chatprocess
node_poller -->|"dispatches resolve"| node_resolution
node_chatprocess -->|"searches context"| node_knowledge
node_chatprocess -->|"fetches page"| node_wikipedia
node_chatprocess -->|"requests ingest"| node_ingest
node_chatprocess -->|"requests answer"| node_llm
node_wikipedia -->|"distils topic"| node_llm
node_ingest -->|"extracts entities"| node_llm
node_wikipedia -->|"fetches article"| node_wiki
node_ingest -->|"stores graph data"| node_graphdb
node_knowledge -->|"retrieves graph context"| node_graphdb
node_knowledge -->|"embeds queries"| node_ollama
node_llm -->|"requests completions"| node_ollama
node_resolution -->|"merges entities"| node_graphdb
node_helpers -->|"updates chat status"| node_graphdb
node_wsgi -->|"serves documentation"| node_docs
node_frontend -.->|"manages knowledge"| node_wsgi
node_frontend -.->|"requests cleanup"| node_resolution
node_messages -.->|"defines request contract"| node_chatprocess

click node_frontend "https://github.com/amilheir/wikigraph/blob/main/src-iris/wsgi/static/wg_check.js"
click node_wsgi "https://github.com/amilheir/wikigraph/blob/main/src-iris/wsgi/app.py"
click node_poller "https://github.com/amilheir/wikigraph/blob/main/src-iris/production/services.py"
click node_chatprocess "https://github.com/amilheir/wikigraph/blob/main/src-iris/production/processes.py"
click node_messages "https://github.com/amilheir/wikigraph/blob/main/src-iris/production/messages.py"
click node_knowledge "https://github.com/amilheir/wikigraph/blob/main/src-iris/production/operations.py"
click node_wikipedia "https://github.com/amilheir/wikigraph/blob/main/src-iris/production/operations.py"
click node_ingest "https://github.com/amilheir/wikigraph/blob/main/src-iris/production/processes.py"
click node_llm "https://github.com/amilheir/wikigraph/blob/main/src-iris/production/operations.py"
click node_resolution "https://github.com/amilheir/wikigraph/blob/main/src-iris/production/operations.py"
click node_helpers "https://github.com/amilheir/wikigraph/blob/main/src-iris/production/common.py"
click node_docs "https://github.com/amilheir/wikigraph/blob/main/src-iris/wsgi/docs/overview.html"

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_frontend,node_docs,node_browser toneBlue
class node_wsgi toneAmber
class node_poller,node_chatprocess,node_messages toneMint
class node_knowledge,node_wikipedia,node_ingest,node_llm,node_resolution,node_helpers toneRose
class node_chatrow,node_graphdb,node_ollama,node_wiki toneIndigo
```

## Components

### Chat interface

- [Chat UI](https://github.com/amilheir/wikigraph/blob/main/src-iris/wsgi/static/wg_check.js): `src-iris/wsgi/static/wg_check.js`
- [Product documentation](https://github.com/amilheir/wikigraph/blob/main/src-iris/wsgi/docs/overview.html): `src-iris/wsgi/docs/overview.html`

### Web API

- [Flask API](https://github.com/amilheir/wikigraph/blob/main/src-iris/wsgi/app.py): `src-iris/wsgi/app.py`

### Interop workflow

- [Polling service](https://github.com/amilheir/wikigraph/blob/main/src-iris/production/services.py): `src-iris/production/services.py`
- [Chat orchestrator](https://github.com/amilheir/wikigraph/blob/main/src-iris/production/processes.py): `src-iris/production/processes.py`
- [Interop messages](https://github.com/amilheir/wikigraph/blob/main/src-iris/production/messages.py): `src-iris/production/messages.py`

### Knowledge pipeline

- [Graph retrieval](https://github.com/amilheir/wikigraph/blob/main/src-iris/production/operations.py): `src-iris/production/operations.py`
- [Wikipedia lookup](https://github.com/amilheir/wikigraph/blob/main/src-iris/production/operations.py): `src-iris/production/operations.py`
- [Article ingestion](https://github.com/amilheir/wikigraph/blob/main/src-iris/production/processes.py): `src-iris/production/processes.py`
- [LLM operations](https://github.com/amilheir/wikigraph/blob/main/src-iris/production/operations.py): `src-iris/production/operations.py`
- [Entity resolution](https://github.com/amilheir/wikigraph/blob/main/src-iris/production/operations.py): `src-iris/production/operations.py`
- [Chunking and helpers](https://github.com/amilheir/wikigraph/blob/main/src-iris/production/common.py): `src-iris/production/common.py`

### IRIS state and models

- **Chat request queue**
- **GraphKB storage**

### Other components

- **Chat user**
- **Ollama models**
- **Wikipedia**

## Connections

- Chat user → Chat UI: uses (evidence: `README.md`)
- Chat UI → Flask API: submits and polls (evidence: `README.md`)
- Flask API → Chat request queue: queues request (evidence: `src-iris/wsgi/app.py`)
- Polling service → Chat request queue: claims queued rows (evidence: `src-iris/production/services.py`)
- Polling service → Chat orchestrator: dispatches chat (evidence: `src-iris/production/services.py`)
- Polling service → Entity resolution: dispatches resolve (evidence: `src-iris/production/services.py`)
- Chat orchestrator → Graph retrieval: searches context (evidence: `src-iris/production/processes.py`)
- Chat orchestrator → Wikipedia lookup: fetches page (evidence: `src-iris/production/processes.py`)
- Chat orchestrator → Article ingestion: requests ingest (evidence: `src-iris/production/processes.py`)
- Chat orchestrator → LLM operations: requests answer (evidence: `src-iris/production/wikiGraph.py`)
- Wikipedia lookup → LLM operations: distils topic (evidence: `src-iris/production/wikiGraph.py`)
- Article ingestion → LLM operations: extracts entities (evidence: `src-iris/production/processes.py`)
- Wikipedia lookup → Wikipedia: fetches article (evidence: `README.md`)
- Article ingestion → GraphKB storage: stores graph data (evidence: `README.md`)
- Graph retrieval → GraphKB storage: retrieves graph context (evidence: `README.md`)
- Graph retrieval → Ollama models: embeds queries (evidence: `README.md`)
- LLM operations → Ollama models: requests completions (evidence: `README.md`)
- Entity resolution → GraphKB storage: merges entities (evidence: `README.md`)
- Chunking and helpers → GraphKB storage: updates chat status (evidence: `src-iris/production/common.py`)
- Flask API → Product documentation: serves documentation (evidence: `src-iris/wsgi/app.py`)
- Chat UI → Flask API: manages knowledge
- Chat UI → Entity resolution: requests cleanup (evidence: `README.md`)
- Interop messages → Chat orchestrator: defines request contract (evidence: `src-iris/production/messages.py`)