# yash-dev007/zephyrus architecture

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

- Interactive diagram: https://gitdiagram.com/yash-dev007/zephyrus
- Repository: https://github.com/yash-dev007/zephyrus

## Overview

Zephyrus is a local-first AI workspace served by one FastAPI app and browser SPA. The main workflow is an authenticated browser request to chat, through chat processing and the agent loop, to a configured model and optional tools, with session state persisted locally. Other major capabilities include personal-document RAG, memory, research and search, and productivity/media features. The README documents the broad architecture; some feature links use its stated module locations because their implementation was not sampled.

Main entry points: [`app.py`](https://github.com/yash-dev007/zephyrus/blob/master/app.py) (FastAPI app), [`src/chat_processor.py`](https://github.com/yash-dev007/zephyrus/blob/master/src/chat_processor.py) (Chat processor), [`src/agent_loop.py`](https://github.com/yash-dev007/zephyrus/blob/master/src/agent_loop.py) (Agent loop), [`services/search`](https://github.com/yash-dev007/zephyrus/tree/master/services/search) (Search service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application edge"]
  node_app_entry["FastAPI app<br/>[app.py]"]
  node_auth["Auth and middleware<br/>[middleware.py]"]
  node_database[("Application database<br/>[database.py]")]
end

subgraph group_assistant["Chat and agents"]
  node_chat_routes["Chat API<br/>[chat_routes.py]"]
  node_chat_processor["Chat processor<br/>[chat_processor.py]"]
  node_agent_loop["Agent loop<br/>[agent_loop.py]"]
  node_tool_execution["Tool execution<br/>[tool_execution.py]"]
  node_session_state["Session manager<br/>[session_manager.py]"]
end

subgraph group_knowledge["Knowledge and research"]
  node_personal_routes["Personal docs API<br/>[personal_routes.py]"]
  node_rag["Document RAG<br/>[rag_manager.py]"]
  node_chroma[("ChromaDB")]
  node_memory_routes["Memory API"]
  node_memory_service["Memory services"]
  node_research_routes["Research API"]
  node_research_handler["Research handler"]
  node_search_routes["Search API<br/>[search_routes.py]"]
  node_search_service["Search service"]
end

subgraph group_workspace["Workspace features"]
  node_email_calendar["Email and calendar<br/>[email_routes.py]"]
  node_tasks_notes["Tasks and notes<br/>[task_routes.py]"]
  node_documents_gallery["Documents and gallery<br/>[document_routes.py]"]
  node_voice["Voice services"]
  node_cookbook["Model cookbook<br/>[cookbook_routes.py]"]
end

subgraph group_integrations["Providers and bridges"]
  node_model_providers{{"Model providers"}}
  node_searxng{{"SearXNG"}}
  node_mcp["MCP manager<br/>[mcp_manager.py]"]
  node_mcp_servers{{"MCP servers"}}
end

node_browser(("Browser SPA"))

node_browser -->|"HTTP and SSE"| node_app_entry
node_app_entry -->|"applies auth"| node_auth
node_app_entry -->|"dispatches"| node_chat_routes
node_chat_routes -->|"processes chat"| node_chat_processor
node_chat_processor -->|"runs agent"| node_agent_loop
node_agent_loop -->|"calls models"| node_model_providers
node_agent_loop -->|"dispatches tools"| node_tool_execution
node_chat_processor -->|"manages sessions"| node_session_state
node_session_state -->|"reads and writes"| node_database
node_personal_routes -->|"manages documents"| node_rag
node_rag -->|"stores vectors"| node_chroma
node_memory_routes -->|"manages memory"| node_memory_service
node_research_routes -->|"starts research"| node_research_handler
node_research_handler -->|"uses search"| node_search_service
node_search_routes -->|"runs queries"| node_search_service
node_search_service -.->|"queries"| node_searxng
node_app_entry -->|"dispatches"| node_email_calendar
node_app_entry -->|"dispatches"| node_tasks_notes
node_app_entry -->|"dispatches"| node_documents_gallery
node_app_entry -->|"dispatches"| node_voice
node_app_entry -->|"dispatches"| node_cookbook
node_tool_execution -->|"uses tools"| node_mcp
node_mcp -->|"dispatches"| node_mcp_servers

click node_browser "https://github.com/yash-dev007/zephyrus/tree/master/static/js"
click node_app_entry "https://github.com/yash-dev007/zephyrus/blob/master/app.py"
click node_auth "https://github.com/yash-dev007/zephyrus/blob/master/core/middleware.py"
click node_chat_routes "https://github.com/yash-dev007/zephyrus/blob/master/routes/chat_routes.py"
click node_chat_processor "https://github.com/yash-dev007/zephyrus/blob/master/src/chat_processor.py"
click node_agent_loop "https://github.com/yash-dev007/zephyrus/blob/master/src/agent_loop.py"
click node_tool_execution "https://github.com/yash-dev007/zephyrus/blob/master/src/tool_execution.py"
click node_session_state "https://github.com/yash-dev007/zephyrus/blob/master/core/session_manager.py"
click node_database "https://github.com/yash-dev007/zephyrus/blob/master/core/database.py"
click node_personal_routes "https://github.com/yash-dev007/zephyrus/blob/master/routes/personal_routes.py"
click node_rag "https://github.com/yash-dev007/zephyrus/blob/master/src/rag_manager.py"
click node_memory_routes "https://github.com/yash-dev007/zephyrus/tree/master/routes/memory"
click node_memory_service "https://github.com/yash-dev007/zephyrus/tree/master/services/memory"
click node_research_routes "https://github.com/yash-dev007/zephyrus/tree/master/routes/research"
click node_research_handler "https://github.com/yash-dev007/zephyrus/blob/master/src/research_handler.py"
click node_search_routes "https://github.com/yash-dev007/zephyrus/blob/master/routes/search_routes.py"
click node_search_service "https://github.com/yash-dev007/zephyrus/tree/master/services/search"
click node_email_calendar "https://github.com/yash-dev007/zephyrus/blob/master/routes/email_routes.py"
click node_tasks_notes "https://github.com/yash-dev007/zephyrus/blob/master/routes/task_routes.py"
click node_documents_gallery "https://github.com/yash-dev007/zephyrus/blob/master/routes/document_routes.py"
click node_voice "https://github.com/yash-dev007/zephyrus/tree/master/services/tts"
click node_cookbook "https://github.com/yash-dev007/zephyrus/blob/master/routes/cookbook_routes.py"
click node_mcp "https://github.com/yash-dev007/zephyrus/blob/master/src/mcp_manager.py"
click node_mcp_servers "https://github.com/yash-dev007/zephyrus/tree/master/mcp_servers"

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_app_entry,node_auth,node_database,node_browser toneBlue
class node_chat_routes,node_chat_processor,node_agent_loop,node_tool_execution,node_session_state toneAmber
class node_personal_routes,node_rag,node_chroma,node_memory_routes,node_memory_service,node_research_routes,node_research_handler,node_search_routes,node_search_service toneMint
class node_email_calendar,node_tasks_notes,node_documents_gallery,node_voice,node_cookbook toneRose
class node_model_providers,node_searxng,node_mcp,node_mcp_servers toneIndigo
```

## Components

### Application edge

- [FastAPI app](https://github.com/yash-dev007/zephyrus/blob/master/app.py): `app.py`
- [Auth and middleware](https://github.com/yash-dev007/zephyrus/blob/master/core/middleware.py): `core/middleware.py`
- [Application database](https://github.com/yash-dev007/zephyrus/blob/master/core/database.py): `core/database.py`

### Chat and agents

- [Chat API](https://github.com/yash-dev007/zephyrus/blob/master/routes/chat_routes.py): `routes/chat_routes.py`
- [Chat processor](https://github.com/yash-dev007/zephyrus/blob/master/src/chat_processor.py): `src/chat_processor.py`
- [Agent loop](https://github.com/yash-dev007/zephyrus/blob/master/src/agent_loop.py): `src/agent_loop.py`
- [Tool execution](https://github.com/yash-dev007/zephyrus/blob/master/src/tool_execution.py): `src/tool_execution.py`
- [Session manager](https://github.com/yash-dev007/zephyrus/blob/master/core/session_manager.py): `core/session_manager.py`

### Knowledge and research

- [Personal docs API](https://github.com/yash-dev007/zephyrus/blob/master/routes/personal_routes.py): `routes/personal_routes.py`
- [Document RAG](https://github.com/yash-dev007/zephyrus/blob/master/src/rag_manager.py): `src/rag_manager.py`
- **ChromaDB**
- [Memory API](https://github.com/yash-dev007/zephyrus/tree/master/routes/memory): `routes/memory`
- [Memory services](https://github.com/yash-dev007/zephyrus/tree/master/services/memory): `services/memory`
- [Research API](https://github.com/yash-dev007/zephyrus/tree/master/routes/research): `routes/research`
- [Research handler](https://github.com/yash-dev007/zephyrus/blob/master/src/research_handler.py): `src/research_handler.py`
- [Search API](https://github.com/yash-dev007/zephyrus/blob/master/routes/search_routes.py): `routes/search_routes.py`
- [Search service](https://github.com/yash-dev007/zephyrus/tree/master/services/search): `services/search`

### Workspace features

- [Email and calendar](https://github.com/yash-dev007/zephyrus/blob/master/routes/email_routes.py): `routes/email_routes.py`
- [Tasks and notes](https://github.com/yash-dev007/zephyrus/blob/master/routes/task_routes.py): `routes/task_routes.py`
- [Documents and gallery](https://github.com/yash-dev007/zephyrus/blob/master/routes/document_routes.py): `routes/document_routes.py`
- [Voice services](https://github.com/yash-dev007/zephyrus/tree/master/services/tts): `services/tts`
- [Model cookbook](https://github.com/yash-dev007/zephyrus/blob/master/routes/cookbook_routes.py): `routes/cookbook_routes.py`

### Providers and bridges

- **Model providers**
- **SearXNG**
- [MCP manager](https://github.com/yash-dev007/zephyrus/blob/master/src/mcp_manager.py): `src/mcp_manager.py`
- [MCP servers](https://github.com/yash-dev007/zephyrus/tree/master/mcp_servers): `mcp_servers`

### Other components

- [Browser SPA](https://github.com/yash-dev007/zephyrus/tree/master/static/js): `static/js`

## Connections

- Browser SPA → FastAPI app: HTTP and SSE
- FastAPI app → Auth and middleware: applies auth
- FastAPI app → Chat API: dispatches
- Chat API → Chat processor: processes chat
- Chat processor → Agent loop: runs agent
- Agent loop → Model providers: calls models
- Agent loop → Tool execution: dispatches tools
- Chat processor → Session manager: manages sessions
- Session manager → Application database: reads and writes
- Personal docs API → Document RAG: manages documents
- Document RAG → ChromaDB: stores vectors
- Memory API → Memory services: manages memory
- Research API → Research handler: starts research
- Research handler → Search service: uses search
- Search API → Search service: runs queries
- Search service → SearXNG: queries
- FastAPI app → Email and calendar: dispatches
- FastAPI app → Tasks and notes: dispatches
- FastAPI app → Documents and gallery: dispatches
- FastAPI app → Voice services: dispatches
- FastAPI app → Model cookbook: dispatches
- Tool execution → MCP manager: uses tools
- MCP manager → MCP servers: dispatches