# lucasastorian/llmwiki architecture

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

- Interactive diagram: https://gitdiagram.com/lucasastorian/llmwiki
- Repository: https://github.com/lucasastorian/llmwiki

## Overview

LLM Wiki captures files, web clips, highlights, and notes into local or hosted knowledge bases; an AI client can then search and maintain wiki pages, while the web app presents sources, pages, and their relationships. The graph shows the documented capture-to-indexing flow and the separate MCP maintenance path. Hosted processing, converter engines, and several UI/API links are represented at subsystem level where the README or source index supports them; unsampled internals are not inferred.

Main entry points: [`api/main.py`](https://github.com/lucasastorian/llmwiki/blob/master/api/main.py) (API application), [`api/domain/local_processor.py`](https://github.com/lucasastorian/llmwiki/blob/master/api/domain/local_processor.py) (Local processor), [`api/services/ocr.py`](https://github.com/lucasastorian/llmwiki/blob/master/api/services/ocr.py) (OCR and extraction), [`mcp/tools/search.py`](https://github.com/lucasastorian/llmwiki/blob/master/mcp/tools/search.py) (MCP tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture"]
  node_extension["Browser clipper<br/>[index.ts]"]
  node_upload["File upload<br/>[local_upload.py]"]
  node_watcher["Workspace watcher<br/>[watcher.py]"]
end

subgraph group_processing["Document processing"]
  node_webparse["Web parser<br/>[parser.py]"]
  node_localprocess["Local processor<br/>[local_processor.py]"]
  node_ocr["OCR and extraction<br/>[ocr.py]"]
  node_converter["Document converter"]
  node_chunker["Text chunker<br/>[chunker.py]"]
end

subgraph group_knowledge["Knowledge services"]
  node_hostedservice["Hosted services<br/>[hosted.py]"]
  node_localservice["Local services<br/>[local.py]"]
  node_quiz["Quiz features<br/>[quiz.py]"]
  node_graph["Knowledge graph<br/>[graph.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_api["API application<br/>[main.py]"]
  node_webapp["Wiki web app<br/>[KBDetail.tsx]"]
  node_mcp["MCP server<br/>[local_server.py]"]
  node_mcptools["MCP tools<br/>[search.py]"]
end

subgraph group_storage["Persistence"]
  node_sqlite[("Local index<br/>[sqlite.py]")]
  node_mcpvault[("MCP vault<br/>[sqlite.py]")]
  node_s3["Object storage<br/>[s3.py]"]
end

node_person(("User"))
node_claude(("AI assistant"))

node_person -->|"clips pages"| node_extension
node_extension -->|"saves clips"| node_api
node_person -->|"uploads files"| node_upload
node_person -->|"adds workspace files"| node_watcher
node_upload -->|"indexes file"| node_localprocess
node_watcher -->|"dispatches processing"| node_localprocess
node_localprocess -->|"updates index"| node_sqlite
node_localprocess -->|"chunks text"| node_chunker
node_localprocess -->|"extracts PDF text"| node_ocr
node_ocr -->|"requests conversion"| node_converter
node_api -->|"parses web clips"| node_webparse
node_person -->|"browses wiki"| node_webapp
node_webapp -->|"uses API"| node_api
node_claude -->|"connects via MCP"| node_mcp
node_mcp -->|"provides tools"| node_mcptools
node_mcptools -->|"searches vault"| node_mcpvault
node_claude -->|"reads and updates wiki"| node_mcptools
node_api -->|"routes hosted requests"| node_hostedservice
node_api -->|"routes local requests"| node_localservice
node_api -->|"serves graph features"| node_graph
node_api -->|"serves quiz features"| node_quiz
node_hostedservice -.->|"stores source files"| node_s3
node_localservice -.->|"uses local index"| node_sqlite
node_api -->|"runs extraction"| node_ocr

click node_extension "https://github.com/lucasastorian/llmwiki/blob/master/extension/src/entrypoints/content/index.ts"
click node_upload "https://github.com/lucasastorian/llmwiki/blob/master/api/routes/local_upload.py"
click node_watcher "https://github.com/lucasastorian/llmwiki/blob/master/api/domain/watcher.py"
click node_webparse "https://github.com/lucasastorian/llmwiki/blob/master/api/html_parser/parser.py"
click node_localprocess "https://github.com/lucasastorian/llmwiki/blob/master/api/domain/local_processor.py"
click node_ocr "https://github.com/lucasastorian/llmwiki/blob/master/api/services/ocr.py"
click node_converter "https://github.com/lucasastorian/llmwiki/blob/master/converter/extraction_service.py"
click node_chunker "https://github.com/lucasastorian/llmwiki/blob/master/api/services/chunker.py"
click node_api "https://github.com/lucasastorian/llmwiki/blob/master/api/main.py"
click node_webapp "https://github.com/lucasastorian/llmwiki/blob/master/web/src/components/kb/KBDetail.tsx"
click node_mcp "https://github.com/lucasastorian/llmwiki/blob/master/mcp/local_server.py"
click node_mcptools "https://github.com/lucasastorian/llmwiki/blob/master/mcp/tools/search.py"
click node_hostedservice "https://github.com/lucasastorian/llmwiki/blob/master/api/services/hosted.py"
click node_localservice "https://github.com/lucasastorian/llmwiki/blob/master/api/services/local.py"
click node_quiz "https://github.com/lucasastorian/llmwiki/blob/master/api/routes/quiz.py"
click node_graph "https://github.com/lucasastorian/llmwiki/blob/master/api/services/graph.py"
click node_sqlite "https://github.com/lucasastorian/llmwiki/blob/master/api/infra/db/sqlite.py"
click node_mcpvault "https://github.com/lucasastorian/llmwiki/blob/master/mcp/vaultfs/sqlite.py"
click node_s3 "https://github.com/lucasastorian/llmwiki/blob/master/api/services/s3.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_extension,node_upload,node_watcher,node_person toneBlue
class node_webparse,node_localprocess,node_ocr,node_converter,node_chunker toneAmber
class node_hostedservice,node_localservice,node_quiz,node_graph toneMint
class node_api,node_webapp,node_mcp,node_mcptools toneRose
class node_sqlite,node_mcpvault,node_s3,node_claude toneIndigo
```

## Components

### Capture

- [Browser clipper](https://github.com/lucasastorian/llmwiki/blob/master/extension/src/entrypoints/content/index.ts): `extension/src/entrypoints/content/index.ts`
- [File upload](https://github.com/lucasastorian/llmwiki/blob/master/api/routes/local_upload.py): `api/routes/local_upload.py`
- [Workspace watcher](https://github.com/lucasastorian/llmwiki/blob/master/api/domain/watcher.py): `api/domain/watcher.py`

### Document processing

- [Web parser](https://github.com/lucasastorian/llmwiki/blob/master/api/html_parser/parser.py): `api/html_parser/parser.py`
- [Local processor](https://github.com/lucasastorian/llmwiki/blob/master/api/domain/local_processor.py): `api/domain/local_processor.py`
- [OCR and extraction](https://github.com/lucasastorian/llmwiki/blob/master/api/services/ocr.py): `api/services/ocr.py`
- [Document converter](https://github.com/lucasastorian/llmwiki/blob/master/converter/extraction_service.py): `converter/extraction_service.py`
- [Text chunker](https://github.com/lucasastorian/llmwiki/blob/master/api/services/chunker.py): `api/services/chunker.py`

### Knowledge services

- [Hosted services](https://github.com/lucasastorian/llmwiki/blob/master/api/services/hosted.py): `api/services/hosted.py`
- [Local services](https://github.com/lucasastorian/llmwiki/blob/master/api/services/local.py): `api/services/local.py`
- [Quiz features](https://github.com/lucasastorian/llmwiki/blob/master/api/routes/quiz.py): `api/routes/quiz.py`
- [Knowledge graph](https://github.com/lucasastorian/llmwiki/blob/master/api/services/graph.py): `api/services/graph.py`

### User interfaces

- [API application](https://github.com/lucasastorian/llmwiki/blob/master/api/main.py): `api/main.py`
- [Wiki web app](https://github.com/lucasastorian/llmwiki/blob/master/web/src/components/kb/KBDetail.tsx): `web/src/components/kb/KBDetail.tsx`
- [MCP server](https://github.com/lucasastorian/llmwiki/blob/master/mcp/local_server.py): `mcp/local_server.py`
- [MCP tools](https://github.com/lucasastorian/llmwiki/blob/master/mcp/tools/search.py): `mcp/tools/search.py`

### Persistence

- [Local index](https://github.com/lucasastorian/llmwiki/blob/master/api/infra/db/sqlite.py): `api/infra/db/sqlite.py`
- [MCP vault](https://github.com/lucasastorian/llmwiki/blob/master/mcp/vaultfs/sqlite.py): `mcp/vaultfs/sqlite.py`
- [Object storage](https://github.com/lucasastorian/llmwiki/blob/master/api/services/s3.py): `api/services/s3.py`

### Other components

- **User**
- **AI assistant**

## Connections

- User → Browser clipper: clips pages
- Browser clipper → API application: saves clips
- User → File upload: uploads files
- User → Workspace watcher: adds workspace files
- File upload → Local processor: indexes file (evidence: `api/routes/local_upload.py`)
- Workspace watcher → Local processor: dispatches processing (evidence: `api/domain/watcher.py`)
- Local processor → Local index: updates index (evidence: `api/domain/local_processor.py`)
- Local processor → Text chunker: chunks text (evidence: `api/domain/local_processor.py`)
- Local processor → OCR and extraction: extracts PDF text (evidence: `api/domain/local_processor.py`)
- OCR and extraction → Document converter: requests conversion (evidence: `api/services/ocr.py`)
- API application → Web parser: parses web clips
- User → Wiki web app: browses wiki
- Wiki web app → API application: uses API
- AI assistant → MCP server: connects via MCP
- MCP server → MCP tools: provides tools (evidence: `mcp/tools/search.py`)
- MCP tools → MCP vault: searches vault (evidence: `mcp/tools/search.py`)
- AI assistant → MCP tools: reads and updates wiki
- API application → Hosted services: routes hosted requests (evidence: `api/main.py`)
- API application → Local services: routes local requests (evidence: `api/main.py`)
- API application → Knowledge graph: serves graph features
- API application → Quiz features: serves quiz features (evidence: `api/main.py`)
- Hosted services → Object storage: stores source files
- Local services → Local index: uses local index
- API application → OCR and extraction: runs extraction (evidence: `api/main.py`)