# q1anyii/mitta architecture

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

- Interactive diagram: https://gitdiagram.com/q1anyii/mitta
- Repository: https://github.com/q1anyii/mitta

## Overview

Mitta is a knowledge-base AI assistant. Its main user workflow is authenticated chat: the API streams a request through ChatService into a LangGraph that routes persona and retrieval intent, optionally runs hybrid RAG, then answers with memory and MCP tools. Separate product branches handle account security, user profiles, file uploads and knowledge-base ingestion. The README documents the retrieval stages and major capabilities; sampled source confirms selected orchestration and service links, so unsampled internal wiring is not expanded.

Main entry points: [`src/graphs/main_graph.py`](https://github.com/q1anyii/mitta/blob/main/src/graphs/main_graph.py) (Main conversation graph), [`src/graphs/nodes/retrieve/query_nodes.py`](https://github.com/q1anyii/mitta/blob/main/src/graphs/nodes/retrieve/query_nodes.py) (Rewrite and recall), [`src/routers/auth_router.py`](https://github.com/q1anyii/mitta/blob/main/src/routers/auth_router.py) (Authentication API), [`src/graphs/retrieve_graph.py`](https://github.com/q1anyii/mitta/blob/main/src/graphs/retrieve_graph.py) (Retrieval subgraph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_api["FastAPI application<br/>[main.py]"]
  node_chat_api["Chat API<br/>[chat_router.py]"]
  node_auth_api["Authentication API<br/>[auth_router.py]"]
  node_login["Login service<br/>[login_service.py]"]
end

subgraph group_agent["Agent workflow"]
  node_chat_service["ChatService<br/>[chat_service.py]"]
  node_graph["Main conversation graph<br/>[main_graph.py]"]
  node_router["Persona and intent router<br/>[router_node.py]"]
end

subgraph group_retrieval["Knowledge retrieval"]
  node_rag["Retrieval subgraph<br/>[retrieve_graph.py]"]
  node_query["Rewrite and recall<br/>[query_nodes.py]"]
  node_fusion["Fusion and reranking<br/>[fusion_nodes.py]"]
  node_output["Retrieval output<br/>[output_node.py]"]
  node_vector[("Vector store<br/>[vector_store.py]")]
end

subgraph group_integrations["Memory and tools"]
  node_cache[("Cache and sparse index<br/>[cache_service.py]")]
  node_memory["Conversation and profile memory<br/>[memory_node.py]"]
  node_profile["User profile service"]
  node_postgres[("PostgreSQL")]
  node_tool_filter["Tool selection<br/>[tool_filter.py]"]
  node_mcp["MCP client<br/>[client.py]"]
end

subgraph group_knowledge["Knowledge management"]
  node_knowledge_api["Knowledge API"]
  node_knowledge_service["Knowledge service"]
  node_upload["File upload and parsing"]
  node_ingest["Incremental ingestion"]
  node_embedding["Document embedding<br/>[embedding.py]"]
end

node_user(("Assistant user"))
node_llm{{"LLM provider"}}
node_mcp_servers{{"MCP tool servers"}}

node_user -->|"sends requests"| node_api
node_api -->|"routes chat"| node_chat_api
node_chat_api -->|"starts stream"| node_chat_service
node_chat_service -->|"runs graph"| node_graph
node_graph -->|"classifies"| node_router
node_router -->|"classifies with"| node_llm
node_graph -->|"retrieves when needed"| node_rag
node_rag -->|"runs recall"| node_query
node_query -->|"rewrites with"| node_llm
node_query -->|"queries vectors"| node_vector
node_query -->|"searches BM25"| node_cache
node_rag -->|"fuses and reranks"| node_fusion
node_fusion -->|"produces results"| node_output
node_graph -->|"generates answer"| node_llm
node_graph -->|"updates memory"| node_memory
node_memory -->|"stores profile"| node_profile
node_profile -->|"persists profile"| node_postgres
node_graph -->|"filters tools"| node_tool_filter
node_graph -->|"invokes tools"| node_mcp
node_mcp -->|"connects tools"| node_mcp_servers
node_user -->|"authenticates"| node_auth_api
node_auth_api -->|"handles account actions"| node_login
node_auth_api -->|"stores token state"| node_cache
node_login -->|"checks users"| node_postgres
node_user -->|"manages knowledge"| node_knowledge_api
node_knowledge_api -->|"delegates knowledge work"| node_knowledge_service
node_knowledge_service -->|"processes files"| node_upload
node_ingest -->|"embeds documents"| node_embedding
node_embedding -->|"writes vectors"| node_vector
node_ingest -->|"writes sparse index"| node_cache

click node_api "https://github.com/q1anyii/mitta/blob/main/src/main.py"
click node_chat_api "https://github.com/q1anyii/mitta/blob/main/src/routers/chat_router.py"
click node_chat_service "https://github.com/q1anyii/mitta/blob/main/src/service/chat_service.py"
click node_graph "https://github.com/q1anyii/mitta/blob/main/src/graphs/main_graph.py"
click node_router "https://github.com/q1anyii/mitta/blob/main/src/graphs/nodes/router_node.py"
click node_rag "https://github.com/q1anyii/mitta/blob/main/src/graphs/retrieve_graph.py"
click node_query "https://github.com/q1anyii/mitta/blob/main/src/graphs/nodes/retrieve/query_nodes.py"
click node_fusion "https://github.com/q1anyii/mitta/blob/main/src/graphs/nodes/retrieve/fusion_nodes.py"
click node_output "https://github.com/q1anyii/mitta/blob/main/src/graphs/nodes/retrieve/output_node.py"
click node_vector "https://github.com/q1anyii/mitta/blob/main/src/vector/vector_store.py"
click node_cache "https://github.com/q1anyii/mitta/blob/main/src/service/cache_service.py"
click node_memory "https://github.com/q1anyii/mitta/blob/main/src/graphs/nodes/memory_node.py"
click node_profile "https://github.com/q1anyii/mitta/blob/main/src/service/user_profile_service.py"
click node_tool_filter "https://github.com/q1anyii/mitta/blob/main/src/graphs/tool_filter.py"
click node_mcp "https://github.com/q1anyii/mitta/blob/main/src/mcp_client/client.py"
click node_auth_api "https://github.com/q1anyii/mitta/blob/main/src/routers/auth_router.py"
click node_login "https://github.com/q1anyii/mitta/blob/main/src/service/login_service.py"
click node_knowledge_api "https://github.com/q1anyii/mitta/blob/main/src/routers/knowledge_router.py"
click node_knowledge_service "https://github.com/q1anyii/mitta/blob/main/src/service/knowledge_service.py"
click node_upload "https://github.com/q1anyii/mitta/blob/main/src/service/file_upload_service.py"
click node_ingest "https://github.com/q1anyii/mitta/blob/main/resources/knowledge-base/ingest_knowledge.py"
click node_embedding "https://github.com/q1anyii/mitta/blob/main/src/vector/embedding.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_api,node_chat_api,node_auth_api,node_login,node_user toneBlue
class node_chat_service,node_graph,node_router toneAmber
class node_rag,node_query,node_fusion,node_output,node_vector,node_mcp_servers toneMint
class node_cache,node_memory,node_profile,node_postgres,node_tool_filter,node_mcp toneRose
class node_knowledge_api,node_knowledge_service,node_upload,node_ingest,node_embedding,node_llm toneIndigo
```

## Components

### API and identity

- [FastAPI application](https://github.com/q1anyii/mitta/blob/main/src/main.py): `src/main.py`
- [Chat API](https://github.com/q1anyii/mitta/blob/main/src/routers/chat_router.py): `src/routers/chat_router.py`
- [Authentication API](https://github.com/q1anyii/mitta/blob/main/src/routers/auth_router.py): `src/routers/auth_router.py`
- [Login service](https://github.com/q1anyii/mitta/blob/main/src/service/login_service.py): `src/service/login_service.py`

### Agent workflow

- [ChatService](https://github.com/q1anyii/mitta/blob/main/src/service/chat_service.py): `src/service/chat_service.py`
- [Main conversation graph](https://github.com/q1anyii/mitta/blob/main/src/graphs/main_graph.py): `src/graphs/main_graph.py`
- [Persona and intent router](https://github.com/q1anyii/mitta/blob/main/src/graphs/nodes/router_node.py): `src/graphs/nodes/router_node.py`

### Knowledge retrieval

- [Retrieval subgraph](https://github.com/q1anyii/mitta/blob/main/src/graphs/retrieve_graph.py): `src/graphs/retrieve_graph.py`
- [Rewrite and recall](https://github.com/q1anyii/mitta/blob/main/src/graphs/nodes/retrieve/query_nodes.py): `src/graphs/nodes/retrieve/query_nodes.py`
- [Fusion and reranking](https://github.com/q1anyii/mitta/blob/main/src/graphs/nodes/retrieve/fusion_nodes.py): `src/graphs/nodes/retrieve/fusion_nodes.py`
- [Retrieval output](https://github.com/q1anyii/mitta/blob/main/src/graphs/nodes/retrieve/output_node.py): `src/graphs/nodes/retrieve/output_node.py`
- [Vector store](https://github.com/q1anyii/mitta/blob/main/src/vector/vector_store.py): `src/vector/vector_store.py`

### Memory and tools

- [Cache and sparse index](https://github.com/q1anyii/mitta/blob/main/src/service/cache_service.py): `src/service/cache_service.py`
- [Conversation and profile memory](https://github.com/q1anyii/mitta/blob/main/src/graphs/nodes/memory_node.py): `src/graphs/nodes/memory_node.py`
- [User profile service](https://github.com/q1anyii/mitta/blob/main/src/service/user_profile_service.py): `src/service/user_profile_service.py`
- **PostgreSQL**
- [Tool selection](https://github.com/q1anyii/mitta/blob/main/src/graphs/tool_filter.py): `src/graphs/tool_filter.py`
- [MCP client](https://github.com/q1anyii/mitta/blob/main/src/mcp_client/client.py): `src/mcp_client/client.py`

### Knowledge management

- [Knowledge API](https://github.com/q1anyii/mitta/blob/main/src/routers/knowledge_router.py): `src/routers/knowledge_router.py`
- [Knowledge service](https://github.com/q1anyii/mitta/blob/main/src/service/knowledge_service.py): `src/service/knowledge_service.py`
- [File upload and parsing](https://github.com/q1anyii/mitta/blob/main/src/service/file_upload_service.py): `src/service/file_upload_service.py`
- [Incremental ingestion](https://github.com/q1anyii/mitta/blob/main/resources/knowledge-base/ingest_knowledge.py): `resources/knowledge-base/ingest_knowledge.py`
- [Document embedding](https://github.com/q1anyii/mitta/blob/main/src/vector/embedding.py): `src/vector/embedding.py`

### Other components

- **Assistant user**
- **LLM provider**
- **MCP tool servers**

## Connections

- Assistant user → FastAPI application: sends requests
- FastAPI application → Chat API: routes chat
- Chat API → ChatService: starts stream
- ChatService → Main conversation graph: runs graph
- Main conversation graph → Persona and intent router: classifies
- Persona and intent router → LLM provider: classifies with
- Main conversation graph → Retrieval subgraph: retrieves when needed
- Retrieval subgraph → Rewrite and recall: runs recall
- Rewrite and recall → LLM provider: rewrites with
- Rewrite and recall → Vector store: queries vectors
- Rewrite and recall → Cache and sparse index: searches BM25
- Retrieval subgraph → Fusion and reranking: fuses and reranks
- Fusion and reranking → Retrieval output: produces results
- Main conversation graph → LLM provider: generates answer
- Main conversation graph → Conversation and profile memory: updates memory
- Conversation and profile memory → User profile service: stores profile
- User profile service → PostgreSQL: persists profile
- Main conversation graph → Tool selection: filters tools
- Main conversation graph → MCP client: invokes tools
- MCP client → MCP tool servers: connects tools
- Assistant user → Authentication API: authenticates
- Authentication API → Login service: handles account actions
- Authentication API → Cache and sparse index: stores token state
- Login service → PostgreSQL: checks users
- Assistant user → Knowledge API: manages knowledge
- Knowledge API → Knowledge service: delegates knowledge work
- Knowledge service → File upload and parsing: processes files
- Incremental ingestion → Document embedding: embeds documents
- Document embedding → Vector store: writes vectors
- Incremental ingestion → Cache and sparse index: writes sparse index