# ayushseal/open-tutor-ai-ce architecture

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

- Interactive diagram: https://gitdiagram.com/ayushseal/open-tutor-ai-ce
- Repository: https://github.com/ayushseal/open-tutor-ai-ce

## Overview

OpenTutorAI is an educational platform for personalized AI tutoring and collaboration. A learner uses the web interface to select a model, submit a chat or multimodal request, and receive a response; chat requests reach the HTTP gateway, which resolves the provider and returns or streams the result. The product also includes knowledge-based retrieval, model and provider administration, adaptive learning supports, user access control, and human-in-the-loop governance. The README documents the broader service/repository/storage flow, but many domain implementations were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`ui/src/lib/components/chat/Chat.svelte`](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ui/src/lib/components/chat/Chat.svelte) (Chat Experience), [`data/database.py`](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/data/database.py) (Application Database), [`gateway/http/api_routes.py`](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/gateway/http/api_routes.py) (Bootstrap API), [`gateway/http/app.py`](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/gateway/http/app.py) (HTTP Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learner Experience"]
  node_web["Web Interface<br/>[+page.svelte]"]
  node_chat_ui["Chat Experience<br/>[Chat.svelte]"]
  node_admin_ui["Admin Workspace<br/>[Settings.svelte]"]
end

subgraph group_gateway["Request Gateway"]
  node_http_app["HTTP Application<br/>[app.py]"]
  node_api_routes["Bootstrap API<br/>[api_routes.py]"]
  node_chat_routes["Chat Routes<br/>[chats.py]"]
  node_auth_routes["Auth Routes<br/>[auth.py]"]
  node_realtime["Realtime Events<br/>[socket.py]"]
end

subgraph group_ai["AI Capabilities"]
  node_providers["Provider Service<br/>[service.py]"]
  node_llm["LLM Service<br/>[service.py]"]
  node_model_catalog["Model Catalog<br/>[service.py]"]
  node_retrieval["Retrieval<br/>[service.py]"]
  node_knowledge["Knowledge Bases<br/>[service.py]"]
  node_media["Voice and Images<br/>[audio.py]"]
end

subgraph group_learning["Learning and Governance"]
  node_learning_supports["Learning Supports<br/>[service.py]"]
  node_sessions["Chat Sessions<br/>[service.py]"]
  node_governance["Self Regulation<br/>[service.py]"]
end

subgraph group_state["Accounts and State"]
  node_account_service["Account Service<br/>[service.py]"]
  node_database[("Application Database<br/>[database.py]")]
end

node_learner(("Learner"))
node_external_models{{"Model Providers"}}

node_learner -->|"uses"| node_web
node_web -->|"sends requests"| node_http_app
node_web -->|"opens chat"| node_chat_ui
node_chat_ui -->|"submits completion"| node_api_routes
node_admin_ui -->|"loads models"| node_api_routes
node_admin_ui -->|"uses APIs"| node_http_app
node_http_app -->|"registers"| node_api_routes
node_http_app -->|"registers"| node_chat_routes
node_http_app -->|"registers"| node_auth_routes
node_api_routes -->|"resolves provider"| node_providers
node_api_routes -->|"proxies completion"| node_external_models
node_providers -->|"queries models"| node_external_models
node_api_routes -->|"emits chat events"| node_realtime
node_chat_routes -->|"chat operations"| node_sessions
node_auth_routes -->|"account operations"| node_account_service
node_account_service -->|"reads and writes"| node_database
node_sessions -->|"reads and writes"| node_database
node_model_catalog -->|"stores model configs"| node_database
node_retrieval -->|"stores retrieval config"| node_database
node_knowledge -->|"knowledge persistence"| node_database
node_learning_supports -->|"stores supports"| node_database
node_governance -->|"governance persistence"| node_database
node_chat_ui -.->|"requests context"| node_retrieval
node_chat_ui -.->|"voice and image use"| node_media
node_chat_ui -.->|"personalized support"| node_learning_supports
node_chat_ui -.->|"response evaluation"| node_governance
node_llm -.->|"provider integration"| node_providers

click node_web "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ui/src/routes/(app)/%2Bpage.svelte"
click node_chat_ui "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ui/src/lib/components/chat/Chat.svelte"
click node_admin_ui "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ui/src/lib/components/admin/Settings.svelte"
click node_http_app "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/gateway/http/app.py"
click node_api_routes "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/gateway/http/api_routes.py"
click node_chat_routes "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/gateway/http/routers/chats.py"
click node_auth_routes "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/gateway/http/routers/auth.py"
click node_realtime "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/gateway/realtime/socket.py"
click node_providers "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ai/providers/service.py"
click node_llm "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ai/llm/service.py"
click node_model_catalog "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ai/model_catalog/service.py"
click node_retrieval "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ai/retrieval/service.py"
click node_knowledge "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ai/retrieval/knowledge/service.py"
click node_media "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ai/media/audio.py"
click node_learning_supports "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/learning/supports/service.py"
click node_sessions "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/learning/sessions/service.py"
click node_governance "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/governance/self_regulation/service.py"
click node_account_service "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/accounts/users/service.py"
click node_database "https://github.com/ayushseal/open-tutor-ai-ce/blob/main/data/database.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_web,node_chat_ui,node_admin_ui toneBlue
class node_http_app,node_api_routes,node_chat_routes,node_auth_routes,node_realtime toneAmber
class node_providers,node_llm,node_model_catalog,node_retrieval,node_knowledge,node_media toneMint
class node_learning_supports,node_sessions,node_governance toneRose
class node_account_service,node_database,node_learner,node_external_models toneIndigo
```

## Components

### Learner Experience

- [Web Interface](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ui/src/routes/(app)/%2Bpage.svelte): `ui/src/routes/(app)/+page.svelte`
- [Chat Experience](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ui/src/lib/components/chat/Chat.svelte): `ui/src/lib/components/chat/Chat.svelte`
- [Admin Workspace](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ui/src/lib/components/admin/Settings.svelte): `ui/src/lib/components/admin/Settings.svelte`

### Request Gateway

- [HTTP Application](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/gateway/http/app.py): `gateway/http/app.py`
- [Bootstrap API](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/gateway/http/api_routes.py): `gateway/http/api_routes.py`
- [Chat Routes](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/gateway/http/routers/chats.py): `gateway/http/routers/chats.py`
- [Auth Routes](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/gateway/http/routers/auth.py): `gateway/http/routers/auth.py`
- [Realtime Events](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/gateway/realtime/socket.py): `gateway/realtime/socket.py`

### AI Capabilities

- [Provider Service](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ai/providers/service.py): `ai/providers/service.py`
- [LLM Service](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ai/llm/service.py): `ai/llm/service.py`
- [Model Catalog](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ai/model_catalog/service.py): `ai/model_catalog/service.py`
- [Retrieval](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ai/retrieval/service.py): `ai/retrieval/service.py`
- [Knowledge Bases](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ai/retrieval/knowledge/service.py): `ai/retrieval/knowledge/service.py`
- [Voice and Images](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/ai/media/audio.py): `ai/media/audio.py`

### Learning and Governance

- [Learning Supports](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/learning/supports/service.py): `learning/supports/service.py`
- [Chat Sessions](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/learning/sessions/service.py): `learning/sessions/service.py`
- [Self Regulation](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/governance/self_regulation/service.py): `governance/self_regulation/service.py`

### Accounts and State

- [Account Service](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/accounts/users/service.py): `accounts/users/service.py`
- [Application Database](https://github.com/ayushseal/open-tutor-ai-ce/blob/main/data/database.py): `data/database.py`

### Other components

- **Learner**
- **Model Providers**

## Connections

- Learner → Web Interface: uses
- Web Interface → HTTP Application: sends requests
- Web Interface → Chat Experience: opens chat
- Chat Experience → Bootstrap API: submits completion
- Admin Workspace → Bootstrap API: loads models
- Admin Workspace → HTTP Application: uses APIs
- HTTP Application → Bootstrap API: registers
- HTTP Application → Chat Routes: registers
- HTTP Application → Auth Routes: registers
- Bootstrap API → Provider Service: resolves provider
- Bootstrap API → Model Providers: proxies completion
- Provider Service → Model Providers: queries models
- Bootstrap API → Realtime Events: emits chat events
- Chat Routes → Chat Sessions: chat operations
- Auth Routes → Account Service: account operations
- Account Service → Application Database: reads and writes
- Chat Sessions → Application Database: reads and writes
- Model Catalog → Application Database: stores model configs
- Retrieval → Application Database: stores retrieval config
- Knowledge Bases → Application Database: knowledge persistence
- Learning Supports → Application Database: stores supports
- Self Regulation → Application Database: governance persistence
- Chat Experience → Retrieval: requests context
- Chat Experience → Voice and Images: voice and image use
- Chat Experience → Learning Supports: personalized support
- Chat Experience → Self Regulation: response evaluation
- LLM Service → Provider Service: provider integration