# tetra4ge/interlock-tg architecture

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

- Interactive diagram: https://gitdiagram.com/tetra4ge/interlock-tg
- Repository: https://github.com/tetra4ge/interlock-tg

## Overview

Interlock builds a temporal corporate-disclosure knowledge graph and answers governance questions through three comparable retrieval architectures: RAG, GraphRAG, and an agentic GraphRAG. Its user-facing workflow is a question sent through the API, answered by a selected pipeline, then presented with evidence; the dashboard also supports live asking, pipeline comparison, quality inspection, and human review of flagged facts. Ingest, parsing, extraction, entity resolution, graph construction, and evaluation are major supporting capabilities. Some subsystem links are based on README descriptions or the SOURCE INDEX; unsampled implementation details are not asserted.

Main entry points: [`server/api`](https://github.com/tetra4ge/interlock-tg/tree/main/server/api) (HTTP API), [`server/pipelines/rag.py`](https://github.com/tetra4ge/interlock-tg/blob/main/server/pipelines/rag.py) (Standard RAG), [`server/pipelines/graphrag/pipeline.py`](https://github.com/tetra4ge/interlock-tg/blob/main/server/pipelines/graphrag/pipeline.py) (GraphRAG), [`server/pipelines/agent/pipeline.py`](https://github.com/tetra4ge/interlock-tg/blob/main/server/pipelines/agent/pipeline.py) (Agentic GraphRAG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_corpus["Disclosure corpus"]
  node_documents["Document acquisition<br/>[fetcher.py]"]
  node_sources["Disclosure sources"]
  node_parsing["PDF parsing<br/>[pdf.py]"]
  node_chunking["Section chunking<br/>[chunk.py]"]
end

subgraph group_knowledge["Knowledge construction"]
  node_extraction["Fact extraction<br/>[runner.py]"]
  node_review["Grounding review<br/>[review.py]"]
  node_resolution["Entity resolution<br/>[mentions.py]"]
  node_graphbuild["Graph loading<br/>[loader.py]"]
  node_graphstore[("TigerGraph")]
  node_vector[("Vector retrieval index<br/>[index.py]")]
  node_store[("Run and corpus store<br/>[db.py]")]
end

subgraph group_answering["Answering pipelines"]
  node_rag["Standard RAG<br/>[rag.py]"]
  node_graphrag["GraphRAG<br/>[pipeline.py]"]
  node_agent["Agentic GraphRAG<br/>[pipeline.py]"]
  node_llm["LLM gateway<br/>[gateway.py]"]
end

subgraph group_product["API and dashboard"]
  node_api["HTTP API"]
  node_dashboard["Research dashboard"]
  node_liveask["Live ask UI<br/>[LiveAsk.tsx]"]
  node_inspector["Pipeline inspector<br/>[page.tsx]"]
  node_qualityui["Quality views<br/>[page.tsx]"]
  node_reviewui["Review queue UI<br/>[page.tsx]"]
end

subgraph group_evaluation["Evaluation and review"]
  node_eval["Evaluation harness<br/>[runner.py]"]
  node_quality["Quality reporting<br/>[quality.py]"]
end

node_user(("Research user"))

node_user -->|"asks and inspects"| node_dashboard
node_dashboard -->|"requests data"| node_api
node_liveask -.->|"submits question"| node_api
node_api -.->|"dispatches pipeline"| node_rag
node_api -.->|"dispatches pipeline"| node_graphrag
node_api -.->|"dispatches pipeline"| node_agent
node_sources -->|"provides filings"| node_documents
node_documents -.->|"fetches for parsing"| node_parsing
node_parsing -.->|"produces text"| node_chunking
node_chunking -->|"embeds chunks"| node_vector
node_chunking -.->|"supplies disclosure text"| node_extraction
node_extraction -->|"flags facts"| node_review
node_extraction -.->|"resolves extracted entities"| node_resolution
node_resolution -.->|"links entities"| node_graphbuild
node_graphbuild -->|"loads graph"| node_graphstore
node_rag -->|"retrieves chunks"| node_vector
node_rag -->|"generates answer"| node_llm
node_graphrag -->|"expands subgraph"| node_graphstore
node_graphrag -->|"falls back to retrieval"| node_vector
node_graphrag -->|"generates answer"| node_llm
node_agent -->|"runs and verifies"| node_llm
node_agent -->|"traverses with tools"| node_graphstore
node_agent -->|"searches text"| node_vector
node_rag -->|"reads excluded docs"| node_store
node_eval -->|"scores pipeline"| node_rag
node_eval -->|"scores pipeline"| node_graphrag
node_eval -->|"scores pipeline"| node_agent
node_qualityui -.->|"shows quality stats"| node_quality
node_reviewui -->|"reviews flagged facts"| node_review
node_inspector -.->|"loads run details"| node_api
node_quality -.->|"reads run metrics"| node_store

click node_api "https://github.com/tetra4ge/interlock-tg/tree/main/server/api"
click node_dashboard "https://github.com/tetra4ge/interlock-tg/tree/main/dashboard/src/app"
click node_liveask "https://github.com/tetra4ge/interlock-tg/blob/main/dashboard/src/components/LiveAsk.tsx"
click node_inspector "https://github.com/tetra4ge/interlock-tg/blob/main/dashboard/src/app/inspector/page.tsx"
click node_qualityui "https://github.com/tetra4ge/interlock-tg/blob/main/dashboard/src/app/data-quality/page.tsx"
click node_reviewui "https://github.com/tetra4ge/interlock-tg/blob/main/dashboard/src/app/review-queue/page.tsx"
click node_documents "https://github.com/tetra4ge/interlock-tg/blob/main/server/ingest/fetcher.py"
click node_sources "https://github.com/tetra4ge/interlock-tg/tree/main/server/ingest/sources"
click node_parsing "https://github.com/tetra4ge/interlock-tg/blob/main/server/parse/pdf.py"
click node_chunking "https://github.com/tetra4ge/interlock-tg/blob/main/server/parse/chunk.py"
click node_extraction "https://github.com/tetra4ge/interlock-tg/blob/main/server/extract/runner.py"
click node_review "https://github.com/tetra4ge/interlock-tg/blob/main/server/extract/review.py"
click node_resolution "https://github.com/tetra4ge/interlock-tg/blob/main/server/resolve/mentions.py"
click node_graphbuild "https://github.com/tetra4ge/interlock-tg/blob/main/server/graph/loader.py"
click node_vector "https://github.com/tetra4ge/interlock-tg/blob/main/server/embed/index.py"
click node_store "https://github.com/tetra4ge/interlock-tg/blob/main/server/store/db.py"
click node_rag "https://github.com/tetra4ge/interlock-tg/blob/main/server/pipelines/rag.py"
click node_graphrag "https://github.com/tetra4ge/interlock-tg/blob/main/server/pipelines/graphrag/pipeline.py"
click node_agent "https://github.com/tetra4ge/interlock-tg/blob/main/server/pipelines/agent/pipeline.py"
click node_llm "https://github.com/tetra4ge/interlock-tg/blob/main/server/llm/gateway.py"
click node_eval "https://github.com/tetra4ge/interlock-tg/blob/main/server/eval/runner.py"
click node_quality "https://github.com/tetra4ge/interlock-tg/blob/main/server/reporting/quality.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_documents,node_sources,node_parsing,node_chunking,node_user toneBlue
class node_extraction,node_review,node_resolution,node_graphbuild,node_graphstore,node_vector,node_store toneAmber
class node_rag,node_graphrag,node_agent,node_llm toneMint
class node_api,node_dashboard,node_liveask,node_inspector,node_qualityui,node_reviewui toneRose
class node_eval,node_quality toneIndigo
```

## Components

### Disclosure corpus

- [Document acquisition](https://github.com/tetra4ge/interlock-tg/blob/main/server/ingest/fetcher.py): `server/ingest/fetcher.py`
- [Disclosure sources](https://github.com/tetra4ge/interlock-tg/tree/main/server/ingest/sources): `server/ingest/sources`
- [PDF parsing](https://github.com/tetra4ge/interlock-tg/blob/main/server/parse/pdf.py): `server/parse/pdf.py`
- [Section chunking](https://github.com/tetra4ge/interlock-tg/blob/main/server/parse/chunk.py): `server/parse/chunk.py`

### Knowledge construction

- [Fact extraction](https://github.com/tetra4ge/interlock-tg/blob/main/server/extract/runner.py): `server/extract/runner.py`
- [Grounding review](https://github.com/tetra4ge/interlock-tg/blob/main/server/extract/review.py): `server/extract/review.py`
- [Entity resolution](https://github.com/tetra4ge/interlock-tg/blob/main/server/resolve/mentions.py): `server/resolve/mentions.py`
- [Graph loading](https://github.com/tetra4ge/interlock-tg/blob/main/server/graph/loader.py): `server/graph/loader.py`
- **TigerGraph**
- [Vector retrieval index](https://github.com/tetra4ge/interlock-tg/blob/main/server/embed/index.py): `server/embed/index.py`
- [Run and corpus store](https://github.com/tetra4ge/interlock-tg/blob/main/server/store/db.py): `server/store/db.py`

### Answering pipelines

- [Standard RAG](https://github.com/tetra4ge/interlock-tg/blob/main/server/pipelines/rag.py): `server/pipelines/rag.py`
- [GraphRAG](https://github.com/tetra4ge/interlock-tg/blob/main/server/pipelines/graphrag/pipeline.py): `server/pipelines/graphrag/pipeline.py`
- [Agentic GraphRAG](https://github.com/tetra4ge/interlock-tg/blob/main/server/pipelines/agent/pipeline.py): `server/pipelines/agent/pipeline.py`
- [LLM gateway](https://github.com/tetra4ge/interlock-tg/blob/main/server/llm/gateway.py): `server/llm/gateway.py`

### API and dashboard

- [HTTP API](https://github.com/tetra4ge/interlock-tg/tree/main/server/api): `server/api`
- [Research dashboard](https://github.com/tetra4ge/interlock-tg/tree/main/dashboard/src/app): `dashboard/src/app`
- [Live ask UI](https://github.com/tetra4ge/interlock-tg/blob/main/dashboard/src/components/LiveAsk.tsx): `dashboard/src/components/LiveAsk.tsx`
- [Pipeline inspector](https://github.com/tetra4ge/interlock-tg/blob/main/dashboard/src/app/inspector/page.tsx): `dashboard/src/app/inspector/page.tsx`
- [Quality views](https://github.com/tetra4ge/interlock-tg/blob/main/dashboard/src/app/data-quality/page.tsx): `dashboard/src/app/data-quality/page.tsx`
- [Review queue UI](https://github.com/tetra4ge/interlock-tg/blob/main/dashboard/src/app/review-queue/page.tsx): `dashboard/src/app/review-queue/page.tsx`

### Evaluation and review

- [Evaluation harness](https://github.com/tetra4ge/interlock-tg/blob/main/server/eval/runner.py): `server/eval/runner.py`
- [Quality reporting](https://github.com/tetra4ge/interlock-tg/blob/main/server/reporting/quality.py): `server/reporting/quality.py`

### Other components

- **Research user**

## Connections

- Research user → Research dashboard: asks and inspects (evidence: `README.md`)
- Research dashboard → HTTP API: requests data (evidence: `README.md`)
- Live ask UI → HTTP API: submits question
- HTTP API → Standard RAG: dispatches pipeline
- HTTP API → GraphRAG: dispatches pipeline
- HTTP API → Agentic GraphRAG: dispatches pipeline
- Disclosure sources → Document acquisition: provides filings (evidence: `README.md`)
- Document acquisition → PDF parsing: fetches for parsing
- PDF parsing → Section chunking: produces text
- Section chunking → Vector retrieval index: embeds chunks (evidence: `server/embed/index.py`)
- Section chunking → Fact extraction: supplies disclosure text
- Fact extraction → Grounding review: flags facts (evidence: `README.md`)
- Fact extraction → Entity resolution: resolves extracted entities
- Entity resolution → Graph loading: links entities
- Graph loading → TigerGraph: loads graph (evidence: `README.md`)
- Standard RAG → Vector retrieval index: retrieves chunks (evidence: `server/pipelines/rag.py`)
- Standard RAG → LLM gateway: generates answer (evidence: `server/pipelines/rag.py`)
- GraphRAG → TigerGraph: expands subgraph (evidence: `README.md`)
- GraphRAG → Vector retrieval index: falls back to retrieval (evidence: `server/pipelines/graphrag/pipeline.py`)
- GraphRAG → LLM gateway: generates answer (evidence: `server/pipelines/graphrag/pipeline.py`)
- Agentic GraphRAG → LLM gateway: runs and verifies (evidence: `server/pipelines/agent/pipeline.py`)
- Agentic GraphRAG → TigerGraph: traverses with tools (evidence: `README.md`)
- Agentic GraphRAG → Vector retrieval index: searches text (evidence: `README.md`)
- Standard RAG → Run and corpus store: reads excluded docs (evidence: `server/pipelines/rag.py`)
- Evaluation harness → Standard RAG: scores pipeline (evidence: `server/eval/runner.py`)
- Evaluation harness → GraphRAG: scores pipeline (evidence: `server/eval/runner.py`)
- Evaluation harness → Agentic GraphRAG: scores pipeline (evidence: `server/eval/runner.py`)
- Quality views → Quality reporting: shows quality stats
- Review queue UI → Grounding review: reviews flagged facts (evidence: `README.md`)
- Pipeline inspector → HTTP API: loads run details
- Quality reporting → Run and corpus store: reads run metrics
