# sm-saqib/agentic_ai_teacher_onica architecture

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

- Interactive diagram: https://gitdiagram.com/sm-saqib/agentic_ai_teacher_onica
- Repository: https://github.com/sm-saqib/agentic_ai_teacher_onica

## Overview

AI Teacher is a self-hosted teaching platform whose implemented core workflow authenticates a learner, opens a conversation, retrieves slide/knowledge context, and generates an LLM answer over REST or streamed WebSocket events. The graph also preserves documented slide, voice, and avatar capabilities; voice/avatar are represented only by their listed module directories, since implementation details are not sampled. Relationships involving unsampled route and feature internals are limited to documented or directly evidenced wiring.

Main entry points: [`backend/app/chat/service.py`](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/chat/service.py) (Conversation service), [`frontend/src/pages/TeachingPage.tsx`](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/pages/TeachingPage.tsx) (Teaching page), [`frontend/src/services/api.ts`](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/services/api.ts) (API client), [`frontend/src/hooks/useChat.ts`](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/hooks/useChat.ts) (Chat workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner interface"]
  node_app["Web application<br/>[App.tsx]"]
  node_teaching["Teaching page<br/>[TeachingPage.tsx]"]
  node_chatui["Chat interface<br/>[ChatWindow.tsx]"]
  node_chatstate["Chat workflow<br/>[useChat.ts]"]
  node_apisvc["API client<br/>[api.ts]"]
  node_wssvc["WebSocket client<br/>[websocket.ts]"]
end

subgraph group_api["Backend API"]
  node_authroute["Auth routes<br/>[auth.py]"]
  node_chatroute["Chat routes<br/>[chat.py]"]
  node_slideroute["Slide routes<br/>[slides.py]"]
  node_wsroute["Chat socket<br/>[router.py]"]
  node_wsmanager["Socket manager<br/>[manager.py]"]
  node_wshandlers["Chat event handlers<br/>[handlers.py]"]
end

subgraph group_learning["Teaching services"]
  node_authsvc["Authentication<br/>[service.py]"]
  node_chatsvc["Conversation service<br/>[service.py]"]
  node_llmclient["LLM selector<br/>[client.py]"]
  node_ollama["Ollama provider<br/>[ollama.py]"]
  node_openrouter["OpenRouter provider<br/>[openrouter.py]"]
  node_voice["Voice capability"]
  node_avatar["Avatar capability"]
end

subgraph group_data["Persistence and indexing"]
  node_database[("PostgreSQL")]
  node_dbmodels["Database models<br/>[models.py]"]
  node_chromaclient["Vector retrieval<br/>[chroma_client.py]"]
  node_chromadb[("ChromaDB")]
  node_slideindex["Slide indexing<br/>[slide_indexer.py]"]
  node_indexer["Vector indexing<br/>[chroma_indexer.py]"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_app
node_app -->|"routes to"| node_teaching
node_teaching -->|"renders"| node_chatui
node_chatui -->|"uses"| node_chatstate
node_chatstate -->|"calls REST"| node_apisvc
node_chatstate -->|"streams via"| node_wssvc
node_apisvc -->|"requests auth"| node_authroute
node_apisvc -->|"requests chat"| node_chatroute
node_apisvc -->|"requests slides"| node_slideroute
node_wssvc -->|"connects"| node_wsroute
node_wsroute -->|"registers and routes"| node_wsmanager
node_wsmanager -->|"dispatches events"| node_wshandlers
node_wshandlers -->|"calls"| node_chatsvc
node_chatroute -->|"delegates chat"| node_chatsvc
node_authroute -->|"delegates auth"| node_authsvc
node_authsvc -->|"reads and writes"| node_database
node_chatsvc -->|"reads and writes"| node_database
node_database -->|"stores"| node_dbmodels
node_chatsvc -->|"retrieves context"| node_chromaclient
node_chromaclient -->|"queries"| node_chromadb
node_chatsvc -->|"generates answers"| node_llmclient
node_llmclient -->|"selects provider"| node_ollama
node_llmclient -->|"selects provider"| node_openrouter
node_slideindex -->|"indexes slides"| node_indexer
node_indexer -->|"adds vectors"| node_chromaclient
node_teaching -.->|"feature area"| node_voice
node_teaching -.->|"feature area"| node_avatar

click node_app "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/App.tsx"
click node_teaching "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/pages/TeachingPage.tsx"
click node_chatui "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/components/chat/ChatWindow.tsx"
click node_chatstate "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/hooks/useChat.ts"
click node_apisvc "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/services/api.ts"
click node_wssvc "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/services/websocket.ts"
click node_authroute "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/api/v1/routes/auth.py"
click node_chatroute "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/api/v1/routes/chat.py"
click node_slideroute "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/api/v1/routes/slides.py"
click node_wsroute "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/api/v1/websocket/router.py"
click node_wsmanager "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/websocket/manager.py"
click node_wshandlers "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/websocket/handlers.py"
click node_authsvc "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/auth/service.py"
click node_chatsvc "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/chat/service.py"
click node_llmclient "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/llm/client.py"
click node_ollama "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/llm/providers/ollama.py"
click node_openrouter "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/llm/providers/openrouter.py"
click node_voice "https://github.com/sm-saqib/agentic_ai_teacher_onica/tree/main/backend/app/voice"
click node_avatar "https://github.com/sm-saqib/agentic_ai_teacher_onica/tree/main/backend/app/avatar"
click node_dbmodels "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/database/models.py"
click node_chromaclient "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/vector_store/chroma_client.py"
click node_slideindex "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/background/indexing/slide_indexer.py"
click node_indexer "https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/background/indexing/chroma_indexer.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_app,node_teaching,node_chatui,node_chatstate,node_apisvc,node_wssvc toneBlue
class node_authroute,node_chatroute,node_slideroute,node_wsroute,node_wsmanager,node_wshandlers toneAmber
class node_authsvc,node_chatsvc,node_llmclient,node_ollama,node_openrouter,node_voice,node_avatar toneMint
class node_database,node_dbmodels,node_chromaclient,node_chromadb,node_slideindex,node_indexer toneRose
class node_learner toneIndigo
```

## Components

### Learner interface

- [Web application](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Teaching page](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/pages/TeachingPage.tsx): `frontend/src/pages/TeachingPage.tsx`
- [Chat interface](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/components/chat/ChatWindow.tsx): `frontend/src/components/chat/ChatWindow.tsx`
- [Chat workflow](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/hooks/useChat.ts): `frontend/src/hooks/useChat.ts`
- [API client](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [WebSocket client](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/frontend/src/services/websocket.ts): `frontend/src/services/websocket.ts`

### Backend API

- [Auth routes](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/api/v1/routes/auth.py): `backend/app/api/v1/routes/auth.py`
- [Chat routes](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/api/v1/routes/chat.py): `backend/app/api/v1/routes/chat.py`
- [Slide routes](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/api/v1/routes/slides.py): `backend/app/api/v1/routes/slides.py`
- [Chat socket](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/api/v1/websocket/router.py): `backend/app/api/v1/websocket/router.py`
- [Socket manager](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/websocket/manager.py): `backend/app/websocket/manager.py`
- [Chat event handlers](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/websocket/handlers.py): `backend/app/websocket/handlers.py`

### Teaching services

- [Authentication](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/auth/service.py): `backend/app/auth/service.py`
- [Conversation service](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/chat/service.py): `backend/app/chat/service.py`
- [LLM selector](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/llm/client.py): `backend/app/llm/client.py`
- [Ollama provider](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/llm/providers/ollama.py): `backend/app/llm/providers/ollama.py`
- [OpenRouter provider](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/llm/providers/openrouter.py): `backend/app/llm/providers/openrouter.py`
- [Voice capability](https://github.com/sm-saqib/agentic_ai_teacher_onica/tree/main/backend/app/voice): `backend/app/voice`
- [Avatar capability](https://github.com/sm-saqib/agentic_ai_teacher_onica/tree/main/backend/app/avatar): `backend/app/avatar`

### Persistence and indexing

- **PostgreSQL**
- [Database models](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/database/models.py): `backend/app/database/models.py`
- [Vector retrieval](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/backend/app/vector_store/chroma_client.py): `backend/app/vector_store/chroma_client.py`
- **ChromaDB**
- [Slide indexing](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/background/indexing/slide_indexer.py): `background/indexing/slide_indexer.py`
- [Vector indexing](https://github.com/sm-saqib/agentic_ai_teacher_onica/blob/main/background/indexing/chroma_indexer.py): `background/indexing/chroma_indexer.py`

### Other components

- **Learner**

## Connections

- Learner → Web application: uses
- Web application → Teaching page: routes to
- Teaching page → Chat interface: renders
- Chat interface → Chat workflow: uses
- Chat workflow → API client: calls REST
- Chat workflow → WebSocket client: streams via
- API client → Auth routes: requests auth
- API client → Chat routes: requests chat
- API client → Slide routes: requests slides
- WebSocket client → Chat socket: connects
- Chat socket → Socket manager: registers and routes
- Socket manager → Chat event handlers: dispatches events
- Chat event handlers → Conversation service: calls
- Chat routes → Conversation service: delegates chat
- Auth routes → Authentication: delegates auth
- Authentication → PostgreSQL: reads and writes
- Conversation service → PostgreSQL: reads and writes
- PostgreSQL → Database models: stores
- Conversation service → Vector retrieval: retrieves context
- Vector retrieval → ChromaDB: queries
- Conversation service → LLM selector: generates answers
- LLM selector → Ollama provider: selects provider
- LLM selector → OpenRouter provider: selects provider
- Slide indexing → Vector indexing: indexes slides
- Vector indexing → Vector retrieval: adds vectors
- Teaching page → Voice capability: feature area
- Teaching page → Avatar capability: feature area