# tabesink/tg-context-engine architecture

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

- Interactive diagram: https://gitdiagram.com/tabesink/tg-context-engine
- Repository: https://github.com/tabesink/tg-context-engine

## Overview

Context Engine is an authenticated document workbench: users upload documents into managed LightRAG Domains, then chat against domain knowledge and browse source documents and graph structure. Document processing creates structured source chunks for indexing and citation; retrieval can combine semantic results with local document navigation, while chat synthesis grounds the response. The client also exposes domain management, library, and graph inspection. TrustGraph is an optional structural-retrieval attachment. The graph emphasizes documented product capabilities and sampled runtime relationships; several route-to-service connections are inferred from the repository’s module responsibilities rather than inspected route bodies.

Main entry points: [`client/src/app/layout.tsx`](https://github.com/tabesink/tg-context-engine/blob/main/client/src/app/layout.tsx) (Next.js workbench), [`app/services/retrieval_service.py`](https://github.com/tabesink/tg-context-engine/blob/main/app/services/retrieval_service.py) (Retrieval coordinator), [`app/services/document_ingestion_coordinator.py`](https://github.com/tabesink/tg-context-engine/blob/main/app/services/document_ingestion_coordinator.py) (Upload and ingestion), [`app/services/lightrag_ingestion_service.py`](https://github.com/tabesink/tg-context-engine/blob/main/app/services/lightrag_ingestion_service.py) (Domain indexing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web workbench"]
  node_web["Next.js workbench<br/>[layout.tsx]"]
  node_chatui["Chat experience"]
  node_libraryui["Document library<br/>[DocumentRoute.tsx]"]
  node_graphui["Graph viewer<br/>[GraphViewer.tsx]"]
end

subgraph group_api["Backend workflows"]
  node_authroutes["Authentication API<br/>[auth.py]"]
  node_uploadroutes["Document API<br/>[documents.py]"]
  node_chatroutes["Chat API<br/>[chat_query.py]"]
  node_retrieveroutes["Retrieval API<br/>[retrieve.py]"]
  node_domainview["Domain management"]
  node_pg[("Application database<br/>[db.py]")]
end

subgraph group_ingestion["Document ingestion"]
  node_upload["Upload and ingestion"]
  node_processing["Structure and chunks<br/>[pipeline.py]"]
  node_ingest["Domain indexing"]
end

subgraph group_query["Retrieval and chat"]
  node_retrieval["Retrieval coordinator"]
  node_navigation["Source navigation"]
  node_synthesis["Answer synthesis<br/>[orchestrator.py]"]
  node_chatservice["Chat turn service"]
end

subgraph group_integrations["Knowledge backends"]
  node_lightrag["LightRAG Domain"]
  node_trustgraph["TrustGraph engine"]
  node_externalservice["TrustGraph service"]
end

node_user(("Workspace user"))

node_user -->|"uses"| node_web
node_web -->|"signs in"| node_authroutes
node_web -->|"uploads files"| node_uploadroutes
node_web -->|"asks questions"| node_chatroutes
node_web -->|"requests evidence"| node_retrieveroutes
node_web -->|"manages domains"| node_domainview
node_web -->|"inspects graph"| node_graphui
node_web -->|"browses sources"| node_libraryui
node_uploadroutes -->|"coordinates ingest"| node_upload
node_upload -->|"parses documents"| node_processing
node_upload -->|"submits chunks"| node_ingest
node_ingest -->|"indexes chunks"| node_lightrag
node_ingest -.->|"pushes chunks"| node_externalservice
node_retrieveroutes -->|"retrieves evidence"| node_retrieval
node_retrieval -->|"searches sources"| node_navigation
node_retrieval -->|"queries domain"| node_lightrag
node_retrieval -.->|"routes structural search"| node_trustgraph
node_trustgraph -.->|"queries graph"| node_externalservice
node_chatroutes -->|"runs turn"| node_chatservice
node_chatservice -->|"gathers evidence"| node_retrieval
node_chatservice -->|"composes answer"| node_synthesis
node_retrieval -->|"reads source structure"| node_pg
node_upload -->|"records documents"| node_pg
node_graphui -->|"loads graph data"| node_lightrag

click node_web "https://github.com/tabesink/tg-context-engine/blob/main/client/src/app/layout.tsx"
click node_chatui "https://github.com/tabesink/tg-context-engine/blob/main/client/src/components/chat/LightRagChatShell.tsx"
click node_libraryui "https://github.com/tabesink/tg-context-engine/blob/main/client/src/features/documents/DocumentRoute.tsx"
click node_graphui "https://github.com/tabesink/tg-context-engine/blob/main/client/src/features/graph/GraphViewer.tsx"
click node_authroutes "https://github.com/tabesink/tg-context-engine/blob/main/app/api/routes/auth.py"
click node_uploadroutes "https://github.com/tabesink/tg-context-engine/blob/main/app/api/routes/documents.py"
click node_chatroutes "https://github.com/tabesink/tg-context-engine/blob/main/app/api/routes/chat_query.py"
click node_retrieveroutes "https://github.com/tabesink/tg-context-engine/blob/main/app/api/routes/retrieve.py"
click node_domainview "https://github.com/tabesink/tg-context-engine/blob/main/app/services/lightrag_domain_view_service.py"
click node_upload "https://github.com/tabesink/tg-context-engine/blob/main/app/services/document_ingestion_coordinator.py"
click node_processing "https://github.com/tabesink/tg-context-engine/blob/main/app/document_processing/pipeline.py"
click node_ingest "https://github.com/tabesink/tg-context-engine/blob/main/app/services/lightrag_ingestion_service.py"
click node_retrieval "https://github.com/tabesink/tg-context-engine/blob/main/app/services/retrieval_service.py"
click node_navigation "https://github.com/tabesink/tg-context-engine/blob/main/app/retrieval/rich_navigation_engine.py"
click node_synthesis "https://github.com/tabesink/tg-context-engine/blob/main/app/chat_synthesis/orchestrator.py"
click node_chatservice "https://github.com/tabesink/tg-context-engine/blob/main/app/services/chat_turn_service.py"
click node_pg "https://github.com/tabesink/tg-context-engine/blob/main/app/storage/db.py"
click node_lightrag "https://github.com/tabesink/tg-context-engine/blob/main/app/integrations/lightrag_remote_adapter.py"
click node_trustgraph "https://github.com/tabesink/tg-context-engine/blob/main/app/retrieval/trustgraph_engine.py"
click node_externalservice "https://github.com/tabesink/tg-context-engine/blob/main/app/integrations/trustgraph_remote_adapter.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_chatui,node_libraryui,node_graphui,node_user toneBlue
class node_authroutes,node_uploadroutes,node_chatroutes,node_retrieveroutes,node_domainview,node_pg toneAmber
class node_upload,node_processing,node_ingest toneMint
class node_retrieval,node_navigation,node_synthesis,node_chatservice toneRose
class node_lightrag,node_trustgraph,node_externalservice toneIndigo
```

## Components

### Web workbench

- [Next.js workbench](https://github.com/tabesink/tg-context-engine/blob/main/client/src/app/layout.tsx): `client/src/app/layout.tsx`
- [Chat experience](https://github.com/tabesink/tg-context-engine/blob/main/client/src/components/chat/LightRagChatShell.tsx): `client/src/components/chat/LightRagChatShell.tsx`
- [Document library](https://github.com/tabesink/tg-context-engine/blob/main/client/src/features/documents/DocumentRoute.tsx): `client/src/features/documents/DocumentRoute.tsx`
- [Graph viewer](https://github.com/tabesink/tg-context-engine/blob/main/client/src/features/graph/GraphViewer.tsx): `client/src/features/graph/GraphViewer.tsx`

### Backend workflows

- [Authentication API](https://github.com/tabesink/tg-context-engine/blob/main/app/api/routes/auth.py): `app/api/routes/auth.py`
- [Document API](https://github.com/tabesink/tg-context-engine/blob/main/app/api/routes/documents.py): `app/api/routes/documents.py`
- [Chat API](https://github.com/tabesink/tg-context-engine/blob/main/app/api/routes/chat_query.py): `app/api/routes/chat_query.py`
- [Retrieval API](https://github.com/tabesink/tg-context-engine/blob/main/app/api/routes/retrieve.py): `app/api/routes/retrieve.py`
- [Domain management](https://github.com/tabesink/tg-context-engine/blob/main/app/services/lightrag_domain_view_service.py): `app/services/lightrag_domain_view_service.py`
- [Application database](https://github.com/tabesink/tg-context-engine/blob/main/app/storage/db.py): `app/storage/db.py`

### Document ingestion

- [Upload and ingestion](https://github.com/tabesink/tg-context-engine/blob/main/app/services/document_ingestion_coordinator.py): `app/services/document_ingestion_coordinator.py`
- [Structure and chunks](https://github.com/tabesink/tg-context-engine/blob/main/app/document_processing/pipeline.py): `app/document_processing/pipeline.py`
- [Domain indexing](https://github.com/tabesink/tg-context-engine/blob/main/app/services/lightrag_ingestion_service.py): `app/services/lightrag_ingestion_service.py`

### Retrieval and chat

- [Retrieval coordinator](https://github.com/tabesink/tg-context-engine/blob/main/app/services/retrieval_service.py): `app/services/retrieval_service.py`
- [Source navigation](https://github.com/tabesink/tg-context-engine/blob/main/app/retrieval/rich_navigation_engine.py): `app/retrieval/rich_navigation_engine.py`
- [Answer synthesis](https://github.com/tabesink/tg-context-engine/blob/main/app/chat_synthesis/orchestrator.py): `app/chat_synthesis/orchestrator.py`
- [Chat turn service](https://github.com/tabesink/tg-context-engine/blob/main/app/services/chat_turn_service.py): `app/services/chat_turn_service.py`

### Knowledge backends

- [LightRAG Domain](https://github.com/tabesink/tg-context-engine/blob/main/app/integrations/lightrag_remote_adapter.py): `app/integrations/lightrag_remote_adapter.py`
- [TrustGraph engine](https://github.com/tabesink/tg-context-engine/blob/main/app/retrieval/trustgraph_engine.py): `app/retrieval/trustgraph_engine.py`
- [TrustGraph service](https://github.com/tabesink/tg-context-engine/blob/main/app/integrations/trustgraph_remote_adapter.py): `app/integrations/trustgraph_remote_adapter.py`

### Other components

- **Workspace user**

## Connections

- Workspace user → Next.js workbench: uses
- Next.js workbench → Authentication API: signs in
- Next.js workbench → Document API: uploads files
- Next.js workbench → Chat API: asks questions
- Next.js workbench → Retrieval API: requests evidence
- Next.js workbench → Domain management: manages domains
- Next.js workbench → Graph viewer: inspects graph
- Next.js workbench → Document library: browses sources
- Document API → Upload and ingestion: coordinates ingest
- Upload and ingestion → Structure and chunks: parses documents
- Upload and ingestion → Domain indexing: submits chunks
- Domain indexing → LightRAG Domain: indexes chunks
- Domain indexing → TrustGraph service: pushes chunks
- Retrieval API → Retrieval coordinator: retrieves evidence
- Retrieval coordinator → Source navigation: searches sources
- Retrieval coordinator → LightRAG Domain: queries domain
- Retrieval coordinator → TrustGraph engine: routes structural search
- TrustGraph engine → TrustGraph service: queries graph
- Chat API → Chat turn service: runs turn
- Chat turn service → Retrieval coordinator: gathers evidence
- Chat turn service → Answer synthesis: composes answer
- Retrieval coordinator → Application database: reads source structure
- Upload and ingestion → Application database: records documents
- Graph viewer → LightRAG Domain: loads graph data