# amjadalisadaf/odysseus architecture

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

- Interactive diagram: https://gitdiagram.com/amjadalisadaf/odysseus
- Repository: https://github.com/amjadalisadaf/odysseus

## Overview

Odysseus is a self-hosted AI workspace. A user works in the browser, sends a chat or agent request, and uses model-backed tools and workspace features such as research, documents, email, notes, and calendar tasks. The backend provides authenticated feature routes, model endpoint selection, shared persistence, and event-triggered task automation. The README documents the product capabilities; sampled source and the SOURCE INDEX support only some internal connections, so unverified wiring is omitted rather than inferred.

Main entry points: [`core/database.py`](https://github.com/amjadalisadaf/odysseus/blob/dev/core/database.py) (Application data), [`routes/chat_routes.py`](https://github.com/amjadalisadaf/odysseus/blob/dev/routes/chat_routes.py) (Chat and agents), [`src/auth_helpers.py`](https://github.com/amjadalisadaf/odysseus/blob/dev/src/auth_helpers.py) (Authentication), [`routes/document/document_routes.py`](https://github.com/amjadalisadaf/odysseus/blob/dev/routes/document/document_routes.py) (Documents and PDFs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Workspace experience"]
  node_browser["Web workspace<br/>[app.js]"]
end

subgraph group_assistant["Chat and intelligence"]
  node_chat_api["Chat and agents<br/>[chat_routes.py]"]
  node_model_routes["Model selection"]
  node_llm["Model interaction<br/>[llm_core.py]"]
  node_tool_runtime["Agent tools<br/>[tool_execution.py]"]
  node_research["Deep research"]
  node_search["Web search<br/>[core.py]"]
end

subgraph group_workspace["Workspace features"]
  node_documents["Documents and PDFs<br/>[document_routes.py]"]
  node_email["Email<br/>[email_routes.py]"]
  node_notes["Notes<br/>[note_routes.py]"]
  node_calendar_tasks["Calendar and tasks<br/>[task_routes.py]"]
end

subgraph group_platform["Application platform"]
  node_session_service["Session management<br/>[session_manager.py]"]
  node_database[("Application data<br/>[database.py]")]
  node_auth["Authentication<br/>[auth_helpers.py]"]
  node_middleware["Request middleware<br/>[middleware.py]"]
end

subgraph group_automation["Tasks and integrations"]
  node_event_bus["Event automation<br/>[event_bus.py]"]
  node_scheduler["Scheduled tasks<br/>[task_scheduler.py]"]
  node_mcp["MCP integrations<br/>[mcp_manager.py]"]
end

node_user(("Workspace user"))
node_external_models{{"Model providers"}}

node_user -->|"uses"| node_browser
node_browser -->|"sends chat"| node_chat_api
node_chat_api -.->|"requests model"| node_llm
node_model_routes -->|"resolves endpoints"| node_llm
node_llm -.->|"calls providers"| node_external_models
node_chat_api -.->|"dispatches tools"| node_tool_runtime
node_user -->|"requests research"| node_research
node_user -->|"searches web"| node_search
node_user -->|"edits documents"| node_documents
node_user -->|"manages email"| node_email
node_user -->|"manages notes"| node_notes
node_user -->|"manages tasks"| node_calendar_tasks
node_chat_api -.->|"uses sessions"| node_session_service
node_session_service -->|"reads and writes"| node_database
node_documents -->|"uses persistence"| node_database
node_email -->|"uses persistence"| node_database
node_notes -->|"uses persistence"| node_database
node_calendar_tasks -->|"uses persistence"| node_database
node_documents -->|"checks access"| node_auth
node_notes -->|"checks access"| node_auth
node_calendar_tasks -->|"checks access"| node_auth
node_middleware -.->|"sets request identity"| node_auth
node_event_bus -->|"loads scheduled tasks"| node_database
node_event_bus -->|"runs triggered task"| node_scheduler
node_user -->|"connects integrations"| node_mcp

click node_browser "https://github.com/amjadalisadaf/odysseus/blob/dev/static/app.js"
click node_chat_api "https://github.com/amjadalisadaf/odysseus/blob/dev/routes/chat_routes.py"
click node_model_routes "https://github.com/amjadalisadaf/odysseus/blob/dev/src/endpoint_resolver.py"
click node_llm "https://github.com/amjadalisadaf/odysseus/blob/dev/src/llm_core.py"
click node_tool_runtime "https://github.com/amjadalisadaf/odysseus/blob/dev/src/tool_execution.py"
click node_research "https://github.com/amjadalisadaf/odysseus/blob/dev/services/research/research_handler.py"
click node_search "https://github.com/amjadalisadaf/odysseus/blob/dev/services/search/core.py"
click node_documents "https://github.com/amjadalisadaf/odysseus/blob/dev/routes/document/document_routes.py"
click node_email "https://github.com/amjadalisadaf/odysseus/blob/dev/routes/email/email_routes.py"
click node_notes "https://github.com/amjadalisadaf/odysseus/blob/dev/routes/note/note_routes.py"
click node_calendar_tasks "https://github.com/amjadalisadaf/odysseus/blob/dev/routes/task/task_routes.py"
click node_session_service "https://github.com/amjadalisadaf/odysseus/blob/dev/core/session_manager.py"
click node_database "https://github.com/amjadalisadaf/odysseus/blob/dev/core/database.py"
click node_auth "https://github.com/amjadalisadaf/odysseus/blob/dev/src/auth_helpers.py"
click node_middleware "https://github.com/amjadalisadaf/odysseus/blob/dev/core/middleware.py"
click node_event_bus "https://github.com/amjadalisadaf/odysseus/blob/dev/src/event_bus.py"
click node_scheduler "https://github.com/amjadalisadaf/odysseus/blob/dev/src/task_scheduler.py"
click node_mcp "https://github.com/amjadalisadaf/odysseus/blob/dev/src/mcp_manager.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_browser,node_user toneBlue
class node_chat_api,node_model_routes,node_llm,node_tool_runtime,node_research,node_search toneAmber
class node_documents,node_email,node_notes,node_calendar_tasks toneMint
class node_session_service,node_database,node_auth,node_middleware toneRose
class node_event_bus,node_scheduler,node_mcp,node_external_models toneIndigo
```

## Components

### Workspace experience

- [Web workspace](https://github.com/amjadalisadaf/odysseus/blob/dev/static/app.js): `static/app.js`

### Chat and intelligence

- [Chat and agents](https://github.com/amjadalisadaf/odysseus/blob/dev/routes/chat_routes.py): `routes/chat_routes.py`
- [Model selection](https://github.com/amjadalisadaf/odysseus/blob/dev/src/endpoint_resolver.py): `src/endpoint_resolver.py`
- [Model interaction](https://github.com/amjadalisadaf/odysseus/blob/dev/src/llm_core.py): `src/llm_core.py`
- [Agent tools](https://github.com/amjadalisadaf/odysseus/blob/dev/src/tool_execution.py): `src/tool_execution.py`
- [Deep research](https://github.com/amjadalisadaf/odysseus/blob/dev/services/research/research_handler.py): `services/research/research_handler.py`
- [Web search](https://github.com/amjadalisadaf/odysseus/blob/dev/services/search/core.py): `services/search/core.py`

### Workspace features

- [Documents and PDFs](https://github.com/amjadalisadaf/odysseus/blob/dev/routes/document/document_routes.py): `routes/document/document_routes.py`
- [Email](https://github.com/amjadalisadaf/odysseus/blob/dev/routes/email/email_routes.py): `routes/email/email_routes.py`
- [Notes](https://github.com/amjadalisadaf/odysseus/blob/dev/routes/note/note_routes.py): `routes/note/note_routes.py`
- [Calendar and tasks](https://github.com/amjadalisadaf/odysseus/blob/dev/routes/task/task_routes.py): `routes/task/task_routes.py`

### Application platform

- [Session management](https://github.com/amjadalisadaf/odysseus/blob/dev/core/session_manager.py): `core/session_manager.py`
- [Application data](https://github.com/amjadalisadaf/odysseus/blob/dev/core/database.py): `core/database.py`
- [Authentication](https://github.com/amjadalisadaf/odysseus/blob/dev/src/auth_helpers.py): `src/auth_helpers.py`
- [Request middleware](https://github.com/amjadalisadaf/odysseus/blob/dev/core/middleware.py): `core/middleware.py`

### Tasks and integrations

- [Event automation](https://github.com/amjadalisadaf/odysseus/blob/dev/src/event_bus.py): `src/event_bus.py`
- [Scheduled tasks](https://github.com/amjadalisadaf/odysseus/blob/dev/src/task_scheduler.py): `src/task_scheduler.py`
- [MCP integrations](https://github.com/amjadalisadaf/odysseus/blob/dev/src/mcp_manager.py): `src/mcp_manager.py`

### Other components

- **Workspace user**
- **Model providers**

## Connections

- Workspace user → Web workspace: uses (evidence: `README.md`)
- Web workspace → Chat and agents: sends chat (evidence: `README.md`)
- Chat and agents → Model interaction: requests model
- Model selection → Model interaction: resolves endpoints (evidence: `src/llm_core.py`)
- Model interaction → Model providers: calls providers
- Chat and agents → Agent tools: dispatches tools
- Workspace user → Deep research: requests research (evidence: `README.md`)
- Workspace user → Web search: searches web (evidence: `README.md`)
- Workspace user → Documents and PDFs: edits documents (evidence: `README.md`)
- Workspace user → Email: manages email (evidence: `README.md`)
- Workspace user → Notes: manages notes (evidence: `README.md`)
- Workspace user → Calendar and tasks: manages tasks (evidence: `README.md`)
- Chat and agents → Session management: uses sessions
- Session management → Application data: reads and writes (evidence: `core/session_manager.py`)
- Documents and PDFs → Application data: uses persistence (evidence: `routes/document/document_routes.py`)
- Email → Application data: uses persistence (evidence: `routes/email/email_routes.py`)
- Notes → Application data: uses persistence (evidence: `routes/note/note_routes.py`)
- Calendar and tasks → Application data: uses persistence (evidence: `routes/task/task_routes.py`)
- Documents and PDFs → Authentication: checks access (evidence: `routes/document/document_routes.py`)
- Notes → Authentication: checks access (evidence: `routes/note/note_routes.py`)
- Calendar and tasks → Authentication: checks access (evidence: `routes/task/task_routes.py`)
- Request middleware → Authentication: sets request identity
- Event automation → Application data: loads scheduled tasks (evidence: `src/event_bus.py`)
- Event automation → Scheduled tasks: runs triggered task (evidence: `src/event_bus.py`)
- Workspace user → MCP integrations: connects integrations (evidence: `README.md`)