# ianloe/twinsphere architecture

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

- Interactive diagram: https://gitdiagram.com/ianloe/twinsphere
- Repository: https://github.com/ianloe/twinsphere

## Overview

TwinSphere is an on-premises personal AI digital twin: users provide documents and memories, then chat with a persona-shaped assistant grounded in that knowledge. The main paths run through FastAPI: ingestion parses and indexes content; chat retrieves vector and graph context, generates a response with a local LLM, and applies voice rules. The graph follows documented and excerpted relationships; some UI proxy wiring and conversation-session integration are not shown in the sampled source.

Main entry points: [`pipeline/twin_engine.py`](https://github.com/ianloe/twinsphere/blob/main/pipeline/twin_engine.py) (Twin engine), [`ingestion/pipeline.py`](https://github.com/ianloe/twinsphere/blob/main/ingestion/pipeline.py) (Ingestion pipeline), [`api/main.py`](https://github.com/ianloe/twinsphere/blob/main/api/main.py) (FastAPI), [`frontend/nginx.conf`](https://github.com/ianloe/twinsphere/blob/main/frontend/nginx.conf) (Frontend proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_chatui["Chat UI<br/>[index.html]"]
  node_adminui["Admin UI<br/>[admin.html]"]
  node_nginx["Frontend proxy<br/>[nginx.conf]"]
end

subgraph group_api["API orchestration"]
  node_api["FastAPI<br/>[main.py]"]
  node_sessions[("Conversation sessions<br/>[session.py]")]
end

subgraph group_knowledge["Knowledge ingestion"]
  node_ingestion["Ingestion pipeline<br/>[pipeline.py]"]
  node_chunker["Document chunker<br/>[chunker.py]"]
  node_extractor["Entity extractor"]
end

subgraph group_retrieval["Retrieval and generation"]
  node_embedder["Ollama embedder<br/>[embedder.py]"]
  node_engine["Twin engine<br/>[twin_engine.py]"]
  node_persona["Persona specification"]
end

subgraph group_stores["Knowledge stores"]
  node_qdrant[("Vector store<br/>[qdrant_client.py]")]
  node_neo4j[("Knowledge graph<br/>[neo4j_client.py]")]
end

node_user(("User"))
node_ollama["Local LLM"]

node_user -->|"asks twin"| node_chatui
node_user -->|"submits content"| node_adminui
node_chatui -->|"serves through"| node_nginx
node_adminui -->|"serves through"| node_nginx
node_nginx -->|"proxies requests"| node_api
node_api -->|"calls chat"| node_engine
node_api -->|"routes ingestion"| node_ingestion
node_ingestion -->|"chunks documents"| node_chunker
node_ingestion -->|"extracts entities"| node_extractor
node_ingestion -->|"embeds content"| node_embedder
node_ingestion -->|"stores vectors"| node_qdrant
node_ingestion -->|"writes graph"| node_neo4j
node_engine -->|"embeds query"| node_embedder
node_engine -->|"searches memories"| node_qdrant
node_engine -->|"expands context"| node_neo4j
node_engine -->|"matches entities"| node_extractor
node_engine -->|"loads persona"| node_persona
node_engine -->|"generates response"| node_ollama
node_api -.->|"persists turns"| node_sessions

click node_chatui "https://github.com/ianloe/twinsphere/blob/main/frontend/index.html"
click node_adminui "https://github.com/ianloe/twinsphere/blob/main/frontend/admin.html"
click node_nginx "https://github.com/ianloe/twinsphere/blob/main/frontend/nginx.conf"
click node_api "https://github.com/ianloe/twinsphere/blob/main/api/main.py"
click node_sessions "https://github.com/ianloe/twinsphere/blob/main/api/middleware/session.py"
click node_ingestion "https://github.com/ianloe/twinsphere/blob/main/ingestion/pipeline.py"
click node_chunker "https://github.com/ianloe/twinsphere/blob/main/pipeline/chunker.py"
click node_extractor "https://github.com/ianloe/twinsphere/blob/main/pipeline/entity_extractor.py"
click node_embedder "https://github.com/ianloe/twinsphere/blob/main/pipeline/embedder.py"
click node_engine "https://github.com/ianloe/twinsphere/blob/main/pipeline/twin_engine.py"
click node_persona "https://github.com/ianloe/twinsphere/blob/main/persona/example_persona.yaml"
click node_qdrant "https://github.com/ianloe/twinsphere/blob/main/vector/qdrant_client.py"
click node_neo4j "https://github.com/ianloe/twinsphere/blob/main/graph/neo4j_client.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_chatui,node_adminui,node_nginx,node_user toneBlue
class node_api,node_sessions toneAmber
class node_ingestion,node_chunker,node_extractor toneMint
class node_embedder,node_engine,node_persona toneRose
class node_qdrant,node_neo4j,node_ollama toneIndigo
```

## Components

### User interaction

- [Chat UI](https://github.com/ianloe/twinsphere/blob/main/frontend/index.html): `frontend/index.html`
- [Admin UI](https://github.com/ianloe/twinsphere/blob/main/frontend/admin.html): `frontend/admin.html`
- [Frontend proxy](https://github.com/ianloe/twinsphere/blob/main/frontend/nginx.conf): `frontend/nginx.conf`

### API orchestration

- [FastAPI](https://github.com/ianloe/twinsphere/blob/main/api/main.py): `api/main.py`
- [Conversation sessions](https://github.com/ianloe/twinsphere/blob/main/api/middleware/session.py): `api/middleware/session.py`

### Knowledge ingestion

- [Ingestion pipeline](https://github.com/ianloe/twinsphere/blob/main/ingestion/pipeline.py): `ingestion/pipeline.py`
- [Document chunker](https://github.com/ianloe/twinsphere/blob/main/pipeline/chunker.py): `pipeline/chunker.py`
- [Entity extractor](https://github.com/ianloe/twinsphere/blob/main/pipeline/entity_extractor.py): `pipeline/entity_extractor.py`

### Retrieval and generation

- [Ollama embedder](https://github.com/ianloe/twinsphere/blob/main/pipeline/embedder.py): `pipeline/embedder.py`
- [Twin engine](https://github.com/ianloe/twinsphere/blob/main/pipeline/twin_engine.py): `pipeline/twin_engine.py`
- [Persona specification](https://github.com/ianloe/twinsphere/blob/main/persona/example_persona.yaml): `persona/example_persona.yaml`

### Knowledge stores

- [Vector store](https://github.com/ianloe/twinsphere/blob/main/vector/qdrant_client.py): `vector/qdrant_client.py`
- [Knowledge graph](https://github.com/ianloe/twinsphere/blob/main/graph/neo4j_client.py): `graph/neo4j_client.py`

### Other components

- **User**
- **Local LLM**

## Connections

- User → Chat UI: asks twin (evidence: `README.md`)
- User → Admin UI: submits content (evidence: `README.md`)
- Chat UI → Frontend proxy: serves through (evidence: `README.md`)
- Admin UI → Frontend proxy: serves through (evidence: `README.md`)
- Frontend proxy → FastAPI: proxies requests (evidence: `README.md`)
- FastAPI → Twin engine: calls chat (evidence: `api/main.py`)
- FastAPI → Ingestion pipeline: routes ingestion (evidence: `api/main.py`)
- Ingestion pipeline → Document chunker: chunks documents (evidence: `ingestion/pipeline.py`)
- Ingestion pipeline → Entity extractor: extracts entities (evidence: `ingestion/pipeline.py`)
- Ingestion pipeline → Ollama embedder: embeds content (evidence: `ingestion/pipeline.py`)
- Ingestion pipeline → Vector store: stores vectors (evidence: `ingestion/pipeline.py`)
- Ingestion pipeline → Knowledge graph: writes graph (evidence: `ingestion/pipeline.py`)
- Twin engine → Ollama embedder: embeds query (evidence: `pipeline/twin_engine.py`)
- Twin engine → Vector store: searches memories (evidence: `pipeline/twin_engine.py`)
- Twin engine → Knowledge graph: expands context (evidence: `pipeline/twin_engine.py`)
- Twin engine → Entity extractor: matches entities (evidence: `pipeline/twin_engine.py`)
- Twin engine → Persona specification: loads persona (evidence: `pipeline/twin_engine.py`)
- Twin engine → Local LLM: generates response (evidence: `pipeline/twin_engine.py`)
- FastAPI → Conversation sessions: persists turns
