# ahaugusto/tusab architecture

> Architecture diagram of the GitHub repository ahaugusto/tusab, 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/ahaugusto/tusab
- Repository: https://github.com/ahaugusto/tusab

## Overview

Tusab is a local-first personal knowledge system: users ingest videos, documents, text, or public research sources; the backend stores and indexes that material, then answers chat queries with retrieved passages and source citations. The graph separates ingestion, retrieval/chat, and study workflows, plus the API/UI and shared persistence layers. README statements support several capabilities whose source was not sampled; those links are documented relationships, not claims of source-level inspection.

Main entry points: [`api_tusab.py`](https://github.com/ahaugusto/tusab/blob/main/api_tusab.py) (REST application), [`tusab_engine/agent/index.py`](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/agent/index.py) (Chunk indexing), [`tusab_engine/agent/chat.py`](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/agent/chat.py) (Cited RAG chat), [`web_interface/src/services/api.js`](https://github.com/ahaugusto/tusab/blob/main/web_interface/src/services/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_ui["Tusab interface<br/>[App.jsx]"]
  node_chat_ui["Chat controls<br/>[useChatEngine.js]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and integration"]
  node_fastapi["REST application<br/>[api_tusab.py]"]
  node_agent_routes["Agent routes<br/>[router_agent.py]"]
  node_ingest_routes["Ingestion routes"]
  node_repository_routes["Repository routes"]
  node_study_routes["Study routes<br/>[router_estudo.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
end

subgraph group_ingest["Knowledge ingestion"]
  node_extractor["YouTube extraction<br/>[extraction.py]"]
  node_source_search["Public source search"]
  node_research["Clinical study search<br/>[fhir.py]"]
  node_document_upload["Document processing"]
end

subgraph group_rag["Retrieval and study"]
  node_indexer["Chunk indexing<br/>[index.py]"]
  node_retrieval["Hybrid retrieval<br/>[fts.py]"]
  node_chat["Cited RAG chat<br/>[chat.py]"]
  node_llm["Model providers<br/>[llm_providers.py]"]
  node_study["Study materials<br/>[router_estudo.py]"]
end

subgraph group_foundation["Shared foundation"]
  node_persistence[("Local data storage<br/>[storage.py]")]
  node_state["Runtime state<br/>[state.py]"]
end

node_user(("Learner"))
node_drive["Google Drive"]
node_llm_services["LLM services"]
node_mcp_clients["MCP-compatible tools"]

node_user -->|"uses"| node_ui
node_ui -->|"requests"| node_api_client
node_chat_ui -->|"streams chat"| node_api_client
node_fastapi -->|"registers"| node_agent_routes
node_fastapi -->|"registers"| node_ingest_routes
node_fastapi -->|"registers"| node_repository_routes
node_fastapi -->|"registers"| node_study_routes
node_api_client -->|"calls REST"| node_fastapi
node_ingest_routes -->|"invokes extraction"| node_extractor
node_repository_routes -->|"receives uploads"| node_document_upload
node_ingest_routes -->|"dispatches searches"| node_source_search
node_repository_routes -.->|"searches studies"| node_research
node_extractor -.->|"indexes content"| node_indexer
node_source_search -->|"indexes results"| node_indexer
node_research -->|"indexes results"| node_indexer
node_document_upload -->|"indexes content"| node_indexer
node_agent_routes -->|"requests indexing"| node_indexer
node_agent_routes -->|"dispatches chat"| node_chat
node_chat_ui -->|"resumes context"| node_api_client
node_chat -->|"retrieves passages"| node_retrieval
node_chat -->|"generates answer"| node_llm
node_llm -->|"sends prompts"| node_llm_services
node_chat -->|"reads and writes"| node_persistence
node_indexer -->|"stores index"| node_persistence
node_study_routes -->|"serves study mode"| node_study
node_study -.->|"saves study items"| node_persistence
node_fastapi -->|"shares runtime state"| node_state
node_mcp_clients -->|"queries knowledge"| node_mcp
node_mcp -.->|"queries assistant"| node_chat
node_ui -.->|"backs up optionally"| node_drive

click node_ui "https://github.com/ahaugusto/tusab/blob/main/web_interface/src/App.jsx"
click node_chat_ui "https://github.com/ahaugusto/tusab/blob/main/web_interface/src/hooks/useChatEngine.js"
click node_api_client "https://github.com/ahaugusto/tusab/blob/main/web_interface/src/services/api.js"
click node_fastapi "https://github.com/ahaugusto/tusab/blob/main/api_tusab.py"
click node_agent_routes "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/api/router_agent.py"
click node_ingest_routes "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/api/router_extraction.py"
click node_repository_routes "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/api/router_repositorio.py"
click node_study_routes "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/api/router_estudo.py"
click node_mcp "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/mcp_server.py"
click node_extractor "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/motor/extraction.py"
click node_source_search "https://github.com/ahaugusto/tusab/tree/main/tusab_engine/motor/fontes"
click node_research "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/motor/fhir.py"
click node_document_upload "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/api/router_repositorio.py"
click node_indexer "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/agent/index.py"
click node_retrieval "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/agent/fts.py"
click node_chat "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/agent/chat.py"
click node_llm "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/agent/llm_providers.py"
click node_study "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/api/router_estudo.py"
click node_persistence "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/storage.py"
click node_state "https://github.com/ahaugusto/tusab/blob/main/tusab_engine/state.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_ui,node_chat_ui,node_api_client toneBlue
class node_fastapi,node_agent_routes,node_ingest_routes,node_repository_routes,node_study_routes,node_mcp toneAmber
class node_extractor,node_source_search,node_research,node_document_upload toneMint
class node_indexer,node_retrieval,node_chat,node_llm,node_study toneRose
class node_persistence,node_state,node_user,node_drive,node_llm_services,node_mcp_clients toneIndigo
```

## Components

### Client experience

- [Tusab interface](https://github.com/ahaugusto/tusab/blob/main/web_interface/src/App.jsx): `web_interface/src/App.jsx`
- [Chat controls](https://github.com/ahaugusto/tusab/blob/main/web_interface/src/hooks/useChatEngine.js): `web_interface/src/hooks/useChatEngine.js`
- [API client](https://github.com/ahaugusto/tusab/blob/main/web_interface/src/services/api.js): `web_interface/src/services/api.js`

### API and integration

- [REST application](https://github.com/ahaugusto/tusab/blob/main/api_tusab.py): `api_tusab.py`
- [Agent routes](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/api/router_agent.py): `tusab_engine/api/router_agent.py`
- [Ingestion routes](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/api/router_extraction.py): `tusab_engine/api/router_extraction.py`
- [Repository routes](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/api/router_repositorio.py): `tusab_engine/api/router_repositorio.py`
- [Study routes](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/api/router_estudo.py): `tusab_engine/api/router_estudo.py`
- [MCP server](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/mcp_server.py): `tusab_engine/mcp_server.py`

### Knowledge ingestion

- [YouTube extraction](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/motor/extraction.py): `tusab_engine/motor/extraction.py`
- [Public source search](https://github.com/ahaugusto/tusab/tree/main/tusab_engine/motor/fontes): `tusab_engine/motor/fontes`
- [Clinical study search](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/motor/fhir.py): `tusab_engine/motor/fhir.py`
- [Document processing](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/api/router_repositorio.py): `tusab_engine/api/router_repositorio.py`

### Retrieval and study

- [Chunk indexing](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/agent/index.py): `tusab_engine/agent/index.py`
- [Hybrid retrieval](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/agent/fts.py): `tusab_engine/agent/fts.py`
- [Cited RAG chat](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/agent/chat.py): `tusab_engine/agent/chat.py`
- [Model providers](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/agent/llm_providers.py): `tusab_engine/agent/llm_providers.py`
- [Study materials](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/api/router_estudo.py): `tusab_engine/api/router_estudo.py`

### Shared foundation

- [Local data storage](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/storage.py): `tusab_engine/storage.py`
- [Runtime state](https://github.com/ahaugusto/tusab/blob/main/tusab_engine/state.py): `tusab_engine/state.py`

### Other components

- **Learner**
- **Google Drive**
- **LLM services**
- **MCP-compatible tools**

## Connections

- Learner → Tusab interface: uses
- Tusab interface → API client: requests (evidence: `web_interface/src/App.jsx`)
- Chat controls → API client: streams chat (evidence: `web_interface/src/hooks/useChatEngine.js`)
- REST application → Agent routes: registers (evidence: `api_tusab.py`)
- REST application → Ingestion routes: registers (evidence: `api_tusab.py`)
- REST application → Repository routes: registers (evidence: `api_tusab.py`)
- REST application → Study routes: registers (evidence: `api_tusab.py`)
- API client → REST application: calls REST
- Ingestion routes → YouTube extraction: invokes extraction (evidence: `tusab_engine/api/router_extraction.py`)
- Repository routes → Document processing: receives uploads (evidence: `tusab_engine/api/router_repositorio.py`)
- Ingestion routes → Public source search: dispatches searches
- Repository routes → Clinical study search: searches studies (evidence: `tusab_engine/api/router_repositorio.py`)
- YouTube extraction → Chunk indexing: indexes content
- Public source search → Chunk indexing: indexes results
- Clinical study search → Chunk indexing: indexes results
- Document processing → Chunk indexing: indexes content
- Agent routes → Chunk indexing: requests indexing (evidence: `tusab_engine/api/router_agent.py`)
- Agent routes → Cited RAG chat: dispatches chat (evidence: `tusab_engine/api/router_agent.py`)
- Chat controls → API client: resumes context (evidence: `web_interface/src/hooks/useChatEngine.js`)
- Cited RAG chat → Hybrid retrieval: retrieves passages (evidence: `tusab_engine/agent/chat.py`)
- Cited RAG chat → Model providers: generates answer (evidence: `tusab_engine/agent/chat.py`)
- Model providers → LLM services: sends prompts
- Cited RAG chat → Local data storage: reads and writes (evidence: `tusab_engine/agent/chat.py`)
- Chunk indexing → Local data storage: stores index (evidence: `tusab_engine/agent/index.py`)
- Study routes → Study materials: serves study mode (evidence: `tusab_engine/api/router_estudo.py`)
- Study materials → Local data storage: saves study items (evidence: `tusab_engine/api/router_estudo.py`)
- REST application → Runtime state: shares runtime state (evidence: `api_tusab.py`)
- MCP-compatible tools → MCP server: queries knowledge
- MCP server → Cited RAG chat: queries assistant
- Tusab interface → Google Drive: backs up optionally
