# nobleborn/runeterra-ai architecture

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

- Interactive diagram: https://gitdiagram.com/nobleborn/runeterra-ai
- Repository: https://github.com/nobleborn/runeterra-ai

## Overview

Runeterra AI is a League of Legends lore assistant: users ask questions in a chat UI and receive locally generated, source-grounded answers. The backend retrieves lore with hybrid semantic and keyword search, selects context, and generates cited answers; it also exposes direct search and streaming chat. A separate ingestion workflow prepares champion lore and stores document chunks and embeddings. The README is empty, so capabilities and relationships here are based on the source index and shown excerpts; unsampled integrations are omitted where their wiring is unclear.

Main entry points: [`backend/app/retrieval/service.py`](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/retrieval/service.py) (Hybrid retriever), [`frontend/src/components/chat/ChatInterface.tsx`](https://github.com/nobleborn/runeterra-ai/blob/main/frontend/src/components/chat/ChatInterface.tsx) (Chat interface), [`backend/app/rag/service.py`](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/rag/service.py) (RAG answer service), [`backend/app/rag/streaming.py`](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/rag/streaming.py) (Streaming answers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chat client"]
  node_chat_ui["Chat interface<br/>[ChatInterface.tsx]"]
  node_chat_input["Chat input<br/>[ChatInput.tsx]"]
  node_chat_message["Chat messages<br/>[ChatMessage.tsx]"]
  node_source_list["Source list<br/>[SourceList.tsx]"]
  node_chat_api["Chat API client<br/>[api.ts]"]
  node_history["Conversation history<br/>[chatHistory.ts]"]
end

subgraph group_api["API and orchestration"]
  node_backend_api["HTTP API<br/>[main.py]"]
end

subgraph group_retrieval["Lore retrieval"]
  node_retriever["Hybrid retriever<br/>[service.py]"]
  node_semantic["Semantic search<br/>[semantic.py]"]
  node_keyword["Keyword search<br/>[keyword.py]"]
  node_query_processing["Keyword processing"]
  node_fusion["Rank fusion<br/>[fusion.py]"]
end

subgraph group_answering["Grounded answering"]
  node_rag_service["RAG answer service<br/>[service.py]"]
  node_streaming["Streaming answers<br/>[streaming.py]"]
  node_rewriter["Query rewriting<br/>[query_rewriter.py]"]
  node_context["Context selection<br/>[context.py]"]
  node_prompts["Answer prompts<br/>[prompts.py]"]
end

subgraph group_ingestion["Lore ingestion"]
  node_ingest_sources["Lore sources<br/>[sources.py]"]
  node_ingest_pipeline["Ingestion pipeline<br/>[pipeline.py]"]
  node_text_processing["Text processing<br/>[text_processing.py]"]
  node_db_connection["Database access<br/>[db.py]"]
  node_ollama_client["Model client<br/>[ollama_client.py]"]
end

node_user(("Lore seeker"))
node_ollama{{"Ollama models"}}
node_database[("Lore database")]

node_user -->|"asks lore"| node_chat_ui
node_chat_ui -->|"renders"| node_chat_input
node_chat_ui -->|"streams request"| node_chat_api
node_chat_ui -->|"builds history"| node_history
node_chat_ui -->|"renders"| node_chat_message
node_chat_message -->|"renders"| node_source_list
node_chat_api -.->|"calls stream"| node_backend_api
node_backend_api -->|"answers chat"| node_rag_service
node_backend_api -->|"streams answer"| node_streaming
node_backend_api -->|"searches lore"| node_retriever
node_rag_service -->|"retrieves passages"| node_retriever
node_rag_service -->|"selects context"| node_context
node_rag_service -->|"uses prompt"| node_prompts
node_rag_service -.->|"generates answer"| node_ollama
node_streaming -->|"retrieves passages"| node_retriever
node_streaming -->|"selects context"| node_context
node_streaming -->|"rewrites query"| node_rewriter
node_streaming -->|"uses prompt"| node_prompts
node_rewriter -->|"rewrites with"| node_ollama
node_retriever -->|"runs search"| node_semantic
node_retriever -->|"runs search"| node_keyword
node_retriever -->|"fuses rankings"| node_fusion
node_keyword -->|"prepares query"| node_query_processing
node_semantic -->|"queries vectors"| node_db_connection
node_semantic -->|"embeds query"| node_ollama_client
node_keyword -->|"queries text"| node_db_connection
node_db_connection -.->|"connects to"| node_database
node_ingest_sources -.->|"supplies documents"| node_ingest_pipeline
node_ingest_pipeline -->|"chunks content"| node_text_processing
node_ingest_pipeline -->|"generates embeddings"| node_ollama_client
node_ingest_pipeline -->|"stores records"| node_db_connection

click node_chat_ui "https://github.com/nobleborn/runeterra-ai/blob/main/frontend/src/components/chat/ChatInterface.tsx"
click node_chat_input "https://github.com/nobleborn/runeterra-ai/blob/main/frontend/src/components/chat/ChatInput.tsx"
click node_chat_message "https://github.com/nobleborn/runeterra-ai/blob/main/frontend/src/components/chat/ChatMessage.tsx"
click node_source_list "https://github.com/nobleborn/runeterra-ai/blob/main/frontend/src/components/chat/SourceList.tsx"
click node_chat_api "https://github.com/nobleborn/runeterra-ai/blob/main/frontend/src/lib/api.ts"
click node_history "https://github.com/nobleborn/runeterra-ai/blob/main/frontend/src/lib/chatHistory.ts"
click node_backend_api "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/main.py"
click node_retriever "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/retrieval/service.py"
click node_semantic "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/retrieval/semantic.py"
click node_keyword "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/retrieval/keyword.py"
click node_query_processing "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/retrieval/query_processing.py"
click node_fusion "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/retrieval/fusion.py"
click node_rag_service "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/rag/service.py"
click node_streaming "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/rag/streaming.py"
click node_rewriter "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/rag/query_rewriter.py"
click node_context "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/rag/context.py"
click node_prompts "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/rag/prompts.py"
click node_ingest_sources "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/ingestion/sources.py"
click node_ingest_pipeline "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/ingestion/pipeline.py"
click node_text_processing "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/ingestion/text_processing.py"
click node_db_connection "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/db.py"
click node_ollama_client "https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/ollama_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_chat_ui,node_chat_input,node_chat_message,node_source_list,node_chat_api,node_history toneBlue
class node_backend_api,node_database toneAmber
class node_retriever,node_semantic,node_keyword,node_query_processing,node_fusion toneMint
class node_rag_service,node_streaming,node_rewriter,node_context,node_prompts toneRose
class node_ingest_sources,node_ingest_pipeline,node_text_processing,node_db_connection,node_ollama_client,node_user,node_ollama toneIndigo
```

## Components

### Chat client

- [Chat interface](https://github.com/nobleborn/runeterra-ai/blob/main/frontend/src/components/chat/ChatInterface.tsx): `frontend/src/components/chat/ChatInterface.tsx`
- [Chat input](https://github.com/nobleborn/runeterra-ai/blob/main/frontend/src/components/chat/ChatInput.tsx): `frontend/src/components/chat/ChatInput.tsx`
- [Chat messages](https://github.com/nobleborn/runeterra-ai/blob/main/frontend/src/components/chat/ChatMessage.tsx): `frontend/src/components/chat/ChatMessage.tsx`
- [Source list](https://github.com/nobleborn/runeterra-ai/blob/main/frontend/src/components/chat/SourceList.tsx): `frontend/src/components/chat/SourceList.tsx`
- [Chat API client](https://github.com/nobleborn/runeterra-ai/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Conversation history](https://github.com/nobleborn/runeterra-ai/blob/main/frontend/src/lib/chatHistory.ts): `frontend/src/lib/chatHistory.ts`

### API and orchestration

- [HTTP API](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/main.py): `backend/app/main.py`

### Lore retrieval

- [Hybrid retriever](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/retrieval/service.py): `backend/app/retrieval/service.py`
- [Semantic search](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/retrieval/semantic.py): `backend/app/retrieval/semantic.py`
- [Keyword search](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/retrieval/keyword.py): `backend/app/retrieval/keyword.py`
- [Keyword processing](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/retrieval/query_processing.py): `backend/app/retrieval/query_processing.py`
- [Rank fusion](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/retrieval/fusion.py): `backend/app/retrieval/fusion.py`

### Grounded answering

- [RAG answer service](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/rag/service.py): `backend/app/rag/service.py`
- [Streaming answers](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/rag/streaming.py): `backend/app/rag/streaming.py`
- [Query rewriting](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/rag/query_rewriter.py): `backend/app/rag/query_rewriter.py`
- [Context selection](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/rag/context.py): `backend/app/rag/context.py`
- [Answer prompts](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/rag/prompts.py): `backend/app/rag/prompts.py`

### Lore ingestion

- [Lore sources](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/ingestion/sources.py): `backend/app/ingestion/sources.py`
- [Ingestion pipeline](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/ingestion/pipeline.py): `backend/app/ingestion/pipeline.py`
- [Text processing](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/ingestion/text_processing.py): `backend/app/ingestion/text_processing.py`
- [Database access](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/db.py): `backend/app/db.py`
- [Model client](https://github.com/nobleborn/runeterra-ai/blob/main/backend/app/ollama_client.py): `backend/app/ollama_client.py`

### Other components

- **Lore seeker**
- **Ollama models**
- **Lore database**

## Connections

- Lore seeker → Chat interface: asks lore
- Chat interface → Chat input: renders (evidence: `frontend/src/components/chat/ChatInterface.tsx`)
- Chat interface → Chat API client: streams request (evidence: `frontend/src/components/chat/ChatInterface.tsx`)
- Chat interface → Conversation history: builds history (evidence: `frontend/src/components/chat/ChatInterface.tsx`)
- Chat interface → Chat messages: renders (evidence: `frontend/src/components/chat/ChatInterface.tsx`)
- Chat messages → Source list: renders (evidence: `frontend/src/components/chat/ChatMessage.tsx`)
- Chat API client → HTTP API: calls stream
- HTTP API → RAG answer service: answers chat (evidence: `backend/app/main.py`)
- HTTP API → Streaming answers: streams answer (evidence: `backend/app/main.py`)
- HTTP API → Hybrid retriever: searches lore (evidence: `backend/app/main.py`)
- RAG answer service → Hybrid retriever: retrieves passages (evidence: `backend/app/rag/service.py`)
- RAG answer service → Context selection: selects context (evidence: `backend/app/rag/service.py`)
- RAG answer service → Answer prompts: uses prompt (evidence: `backend/app/rag/service.py`)
- RAG answer service → Ollama models: generates answer
- Streaming answers → Hybrid retriever: retrieves passages (evidence: `backend/app/rag/streaming.py`)
- Streaming answers → Context selection: selects context (evidence: `backend/app/rag/streaming.py`)
- Streaming answers → Query rewriting: rewrites query (evidence: `backend/app/rag/streaming.py`)
- Streaming answers → Answer prompts: uses prompt (evidence: `backend/app/rag/streaming.py`)
- Query rewriting → Ollama models: rewrites with (evidence: `backend/app/rag/query_rewriter.py`)
- Hybrid retriever → Semantic search: runs search (evidence: `backend/app/retrieval/service.py`)
- Hybrid retriever → Keyword search: runs search (evidence: `backend/app/retrieval/service.py`)
- Hybrid retriever → Rank fusion: fuses rankings (evidence: `backend/app/retrieval/service.py`)
- Keyword search → Keyword processing: prepares query (evidence: `backend/app/retrieval/keyword.py`)
- Semantic search → Database access: queries vectors (evidence: `backend/app/retrieval/semantic.py`)
- Semantic search → Model client: embeds query (evidence: `backend/app/retrieval/semantic.py`)
- Keyword search → Database access: queries text (evidence: `backend/app/retrieval/keyword.py`)
- Database access → Lore database: connects to
- Lore sources → Ingestion pipeline: supplies documents
- Ingestion pipeline → Text processing: chunks content (evidence: `backend/app/ingestion/pipeline.py`)
- Ingestion pipeline → Model client: generates embeddings (evidence: `backend/app/ingestion/pipeline.py`)
- Ingestion pipeline → Database access: stores records (evidence: `backend/app/ingestion/pipeline.py`)
