# open-tutorai/open-tutor-ai-ce architecture

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

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

## Overview

##### Project Type and Purpose
- This is a full-stack, educational AI platform (Open TutorAI-CE).
- Frontend: SvelteKit/PWA for web and mobile.
- Backend: Python-based API (FastAPI style routers) serving authentication, chat, RAG, media, admin functions.
- Integrations: Ollama & OpenAI-compatible LLM services, RAG, image generation, voice/video, web search.

##### Main Components
a. End User & UI Layer
- Students, teachers, admins access via browser or installed PWA.
- UI built in SvelteKit (static assets served by Vite, Caddy or CDN).
b. Frontend Server
- SvelteKit SSR and API proxy.
- Service Worker for offline PWA mode.
c. Backend API Service
- Python application with separated routers (auth, chats, supports, feedback, admin).
- Business logic for RAG (file ingestion, vector store), avatar, voice/video signaling.
d. Data Layer
- Relational database (e.g., PostgreSQL) accessed via SQLAlchemy (backend/models/database.py).
- File storage (attachments, classroom documents) on disk or object store.
- Vector database or in-process vector index for retrieval.
e. Background Workers (optional)
- Pyodide, KokoroWorker, image generation pipelines for heavy tasks.
f. External Services
- Ollama local model server (Docker container).
- OpenAI-compatible endpoints (Mistral, LMStudio, etc.).
- Web search providers (Google PSE, DuckDuckGo) for RAG.
- Image generation APIs (AUTOMATIC1111, DALL-E).
g. Infrastructure & Deployment
- Docker Compose or Kubernetes (Helm charts).
- Reverse proxy (Caddyfile) and environment config.

##### Relationships & Data Flows
- Users ↔ Browser/PWA UI (HTTP/WebSocket)
- UI → Frontend Server (SSR requests, static asset fetch)
- UI → Backend API (REST over HTTPS)
- Backend API ↔ Database (CRUD, sessions, RBAC)
- Backend API ↔ File Storage / Vector Store (RAG retrieval)
- Backend API ↔ External LLM Services (Ollama, OpenAI)
- Backend API ↔ Web Search / Image‐Gen APIs
- Backend API → Background Workers (via message queue or direct spawn)
- Optionally: UI ↔ Backend for WebRTC signaling (voice/video)

##### Architectural Patterns & Design Principles
- Separation of concerns: UI vs. API vs. data vs. workers.
- Modular routers in backend (FastAPI “routers” for each domain).
- PWA offline-first via service worker.
- Role-based access control (RBAC) enforced in API layer.
- RAG pattern: ingestion → vector indexing → retrieval during chat.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Users and UI
    User["End User\n(Student/Teacher/Admin)"]:::user
    UI["Browser/PWA\n(SvelteKit)"]:::frontend
    UILib["UI Library\n(src/lib/components/)"]:::frontend
    SW["Service Worker\n(src/lib/workers/pyodide.worker.ts)"]:::frontend

    User -->|"interacts via HTTPS/WS"| UI
    UI -->|"uses components"| UILib
    UI -->|"offline caching"| SW

    click UI "https://github.com/open-tutorai/open-tutor-ai-ce/tree/main/src/routes/"
    click UILib "https://github.com/open-tutorai/open-tutor-ai-ce/tree/main/src/lib/components/"
    click SW "https://github.com/open-tutorai/open-tutor-ai-ce/blob/main/src/lib/workers/pyodide.worker.ts"

    %% Frontend Server
    FWServer["Frontend Server\n(SSR & Proxy)"]:::frontend
    User -->|"SSR/Proxy requests"| FWServer
    click FWServer "https://github.com/open-tutorai/open-tutor-ai-ce/blob/main/svelte.config.js"

    %% Backend API
    subgraph "Backend API Service"
        direction TB
        Main["main.py"]:::backend
        Config["config/\nenv.py\nconfig.py"]:::backend
        Routers["Routers\n(open_tutorai/routers/)"]:::backend
        Logic["Business Logic\n(patches.py)"]:::backend
        Requirements["requirements.txt\nstart.sh\ndev.sh"]:::backend
    end

    FWServer -->|"REST over HTTPS"| Main
    click Main "https://github.com/open-tutorai/open-tutor-ai-ce/blob/main/backend/open_tutorai/main.py"
    click Config "https://github.com/open-tutorai/open-tutor-ai-ce/tree/main/backend/open_tutorai/config/"
    click Routers "https://github.com/open-tutorai/open-tutor-ai-ce/tree/main/backend/open_tutorai/routers/"
    click Logic "https://github.com/open-tutorai/open-tutor-ai-ce/blob/main/backend/open_tutorai/patches.py"
    click Requirements "https://github.com/open-tutorai/open-tutor-ai-ce/blob/main/backend/requirements.txt"

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB["PostgreSQL\n(models/database.py)"]:::database
        FileStore["File Storage\n(static/)"]:::database
        VectorStore["Vector Store\n(rag/index.ts)"]:::database
    end

    Main -->|"CRUD via SQLAlchemy"| DB
    Main -->|"store/retrieve files"| FileStore
    Main -->|"vector RAG queries"| VectorStore

    click DB "https://github.com/open-tutorai/open-tutor-ai-ce/blob/main/backend/open_tutorai/models/database.py"
    click FileStore "https://github.com/open-tutorai/open-tutor-ai-ce/tree/main/static/"
    click VectorStore "https://github.com/open-tutorai/open-tutor-ai-ce/blob/main/src/lib/utils/rag/index.ts"

    %% Background Workers
    subgraph "Background Workers"
        direction TB
        RAGWorker["RAG & Ingestion Worker\n(KokoroWorker.ts)"]:::worker
        PyodideWorker["Pyodide Worker\n(pyodide.worker.ts)"]:::worker
    end

    Main -->|"async tasks via AMQP"| RAGWorker
    Main -->|"spawn in-browser"| PyodideWorker

    click RAGWorker "https://github.com/open-tutorai/open-tutor-ai-ce/blob/main/src/lib/workers/KokoroWorker.ts"
    click PyodideWorker "https://github.com/open-tutorai/open-tutor-ai-ce/blob/main/src/lib/workers/pyodide.worker.ts"

    %% External Services
    subgraph "External Services"
        direction TB
        Ollama["Ollama LLM\n(Docker)"]:::external
        OpenAI["OpenAI-compatible LLMs"]:::external
        WebSearch["Web Search APIs"]:::external
        ImageGen["Image Gen APIs"]:::external
    end

    Main -->|"gRPC/HTTP"| Ollama
    Main -->|"HTTP REST"| OpenAI
    Main -->|"HTTPS RAG query"| WebSearch
    Main -->|"API calls"| ImageGen

    %% Legend
    subgraph "Legend"
        direction LR
        U["User"]:::user
        FE["Frontend"]:::frontend
        BE["Backend"]:::backend
        DBs["Database/Storage"]:::database
        WK["Workers"]:::worker
        EX["External"]:::external
    end

    classDef user fill:#e3f2fd,stroke:#42a5f5,color:#0d47a1;
    classDef frontend fill:#e1f5fe,stroke:#0288d1,color:#01579b;
    classDef backend fill:#e8f5e9,stroke:#43a047,color:#1b5e20;
    classDef database fill:#fff3e0,stroke:#fb8c00,color:#e65100;
    classDef worker fill:#eceff1,stroke:#607d8b,color:#263238;
    classDef external fill:#ffebee,stroke:#e53935,color:#b71c1c;
```
