How yash-dev007/zephyrus works
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 FastAPI app · chat_processor.py Chat processor · agent_loop.py Agent loop · search Search service
Components 27
Application edge
- FastAPI app
app.py - Auth and middleware
core/middleware.py - Application database
core/database.py
Chat and agents
- Chat API
routes/chat_routes.py - Chat processor
src/chat_processor.py - Agent loop
src/agent_loop.py - Tool execution
src/tool_execution.py - Session manager
core/session_manager.py
Knowledge and research
- Personal docs API
routes/personal_routes.py - Document RAG
src/rag_manager.py - ChromaDB
- Memory API
routes/memory - Memory services
services/memory - Research API
routes/research - Research handler
src/research_handler.py - Search API
routes/search_routes.py - Search service
services/search
Workspace features
- Email and calendar
routes/email_routes.py - Tasks and notes
routes/task_routes.py - Documents and gallery
routes/document_routes.py - Voice services
services/tts - Model cookbook
routes/cookbook_routes.py
Providers and bridges
- Model providers
- SearXNG
- MCP manager
src/mcp_manager.py - MCP servers
mcp_servers
Other components
- Browser SPA
static/js
Connections 23
- 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