# git-me-harish/mentora architecture

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

- Interactive diagram: https://gitdiagram.com/git-me-harish/mentora
- Repository: https://github.com/git-me-harish/mentora

## Overview

Mentora is an adaptive AI learning platform. A learner uses the web app to access the FastAPI service; the documented tutoring flow routes questions, retrieves cited learning content, and returns an AI response. Other major branches personalize learning through mastery, spaced repetition, recommendations, and adaptive paths, and support documents, collaboration, analytics, and beta/PWA features. The graph combines README-documented capabilities with source-index references; links to unsampled subsystems are limited to documented relationships.

Main entry points: [`ai_service/main.py`](https://github.com/git-me-harish/mentora/blob/main/ai_service/main.py) (FastAPI app), [`ai_service/services/rag_service.py`](https://github.com/git-me-harish/mentora/blob/main/ai_service/services/rag_service.py) (RAG retrieval), [`ai_service/routers/adaptive.py`](https://github.com/git-me-harish/mentora/blob/main/ai_service/routers/adaptive.py) (Adaptive API), [`ai_service/pipelines/tutor_pipeline.py`](https://github.com/git-me-harish/mentora/blob/main/ai_service/pipelines/tutor_pipeline.py) (Tutor orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner app"]
  node_webapp["Web app<br/>[page.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["API and identity"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_auth["Identity<br/>[auth.py]"]
  node_security["Security<br/>[security.py]"]
  node_observability["Observability<br/>[observability.py]"]
  node_chat_api["Chat API<br/>[chat.py]"]
end

subgraph group_learning["Adaptive learning"]
  node_adaptive_api["Adaptive API<br/>[adaptive.py]"]
  node_bkt["BKT mastery<br/>[bkt_engine.py]"]
  node_dkt["DKT mastery<br/>[dkt_engine.py]"]
  node_spaced["Spaced repetition<br/>[sm2_engine.py]"]
  node_path_optimizer["Path optimizer<br/>[dqn_optimizer.py]"]
  node_recommendations["Recommendations"]
end

subgraph group_tutoring["Tutoring and content"]
  node_tutor_pipeline["Tutor orchestration<br/>[tutor_pipeline.py]"]
  node_query_router["Query routing<br/>[query_router.py]"]
  node_query_transform["Query transform<br/>[query_transform.py]"]
  node_rag["RAG retrieval<br/>[rag_service.py]"]
  node_embedding["Embeddings"]
  node_qdrant[("Vector store")]
  node_documents["Document processing<br/>[document_worker.py]"]
  node_storage[("Object storage<br/>[storage_service.py]")]
end

subgraph group_community["Community and operations"]
  node_social_api["Social sessions<br/>[study_sessions.py]"]
  node_livekit["Live sessions<br/>[livekit_service.py]"]
  node_audit["Audit and consent"]
  node_analytics["Learning analytics"]
  node_beta_pwa["Beta and offline<br/>[pwa_sync.py]"]
  node_celery_social["Social background tasks<br/>[social_tasks.py]"]
  node_email["Email delivery<br/>[email_service.py]"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_webapp
node_webapp -->|"requests"| node_api_client
node_api_client -->|"calls API"| node_api_app
node_api_app -->|"registers routes"| node_auth
node_api_app -->|"registers routes"| node_chat_api
node_api_app -->|"registers routes"| node_adaptive_api
node_auth -->|"uses"| node_security
node_chat_api -->|"calls"| node_rag
node_chat_api -.->|"orchestrates"| node_tutor_pipeline
node_tutor_pipeline -->|"routes queries"| node_query_router
node_query_router -->|"reuses helper"| node_query_transform
node_tutor_pipeline -->|"transforms queries"| node_query_transform
node_tutor_pipeline -->|"retrieves context"| node_rag
node_rag -->|"embeds queries"| node_embedding
node_rag -->|"expands queries"| node_query_transform
node_rag -->|"searches vectors"| node_qdrant
node_documents -->|"fetches uploads"| node_storage
node_documents -->|"indexes chunks"| node_rag
node_adaptive_api -->|"updates mastery"| node_bkt
node_adaptive_api -->|"schedules reviews"| node_spaced
node_adaptive_api -.->|"optimizes paths"| node_path_optimizer
node_adaptive_api -.->|"estimates mastery"| node_dkt
node_learner -->|"joins sessions"| node_social_api
node_social_api -->|"creates rooms"| node_livekit
node_social_api -->|"schedules tasks"| node_celery_social
node_api_app -.->|"configures telemetry"| node_observability
node_api_app -.->|"enforces compliance"| node_audit
node_api_app -.->|"serves dashboards"| node_analytics
node_api_app -->|"registers routes"| node_beta_pwa
node_celery_social -.->|"sends notices"| node_email

click node_webapp "https://github.com/git-me-harish/mentora/blob/main/frontend/src/app/(app)/chat/page.tsx"
click node_api_client "https://github.com/git-me-harish/mentora/blob/main/frontend/src/lib/api/client.ts"
click node_api_app "https://github.com/git-me-harish/mentora/blob/main/ai_service/main.py"
click node_auth "https://github.com/git-me-harish/mentora/blob/main/ai_service/routers/auth.py"
click node_security "https://github.com/git-me-harish/mentora/blob/main/ai_service/core/security.py"
click node_observability "https://github.com/git-me-harish/mentora/blob/main/ai_service/core/observability.py"
click node_chat_api "https://github.com/git-me-harish/mentora/blob/main/ai_service/routers/chat.py"
click node_adaptive_api "https://github.com/git-me-harish/mentora/blob/main/ai_service/routers/adaptive.py"
click node_bkt "https://github.com/git-me-harish/mentora/blob/main/ai_service/engines/bkt_engine.py"
click node_dkt "https://github.com/git-me-harish/mentora/blob/main/ai_service/engines/dkt_engine.py"
click node_spaced "https://github.com/git-me-harish/mentora/blob/main/ai_service/engines/sm2_engine.py"
click node_path_optimizer "https://github.com/git-me-harish/mentora/blob/main/ai_service/engines/dqn_optimizer.py"
click node_recommendations "https://github.com/git-me-harish/mentora/blob/main/ai_service/services/recommendation_service.py"
click node_tutor_pipeline "https://github.com/git-me-harish/mentora/blob/main/ai_service/pipelines/tutor_pipeline.py"
click node_query_router "https://github.com/git-me-harish/mentora/blob/main/ai_service/pipelines/query_router.py"
click node_query_transform "https://github.com/git-me-harish/mentora/blob/main/ai_service/pipelines/query_transform.py"
click node_rag "https://github.com/git-me-harish/mentora/blob/main/ai_service/services/rag_service.py"
click node_embedding "https://github.com/git-me-harish/mentora/blob/main/ai_service/services/embedding_service.py"
click node_documents "https://github.com/git-me-harish/mentora/blob/main/ai_service/workers/document_worker.py"
click node_storage "https://github.com/git-me-harish/mentora/blob/main/ai_service/services/storage_service.py"
click node_social_api "https://github.com/git-me-harish/mentora/blob/main/ai_service/routers/study_sessions.py"
click node_livekit "https://github.com/git-me-harish/mentora/blob/main/ai_service/services/livekit_service.py"
click node_audit "https://github.com/git-me-harish/mentora/blob/main/ai_service/services/audit_log_service.py"
click node_analytics "https://github.com/git-me-harish/mentora/blob/main/ai_service/services/analytics_service.py"
click node_beta_pwa "https://github.com/git-me-harish/mentora/blob/main/ai_service/routers/pwa_sync.py"
click node_celery_social "https://github.com/git-me-harish/mentora/blob/main/ai_service/workers/tasks/social_tasks.py"
click node_email "https://github.com/git-me-harish/mentora/blob/main/ai_service/services/email_service.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_webapp,node_api_client toneBlue
class node_api_app,node_auth,node_security,node_observability,node_chat_api toneAmber
class node_adaptive_api,node_bkt,node_dkt,node_spaced,node_path_optimizer,node_recommendations toneMint
class node_tutor_pipeline,node_query_router,node_query_transform,node_rag,node_embedding,node_qdrant,node_documents,node_storage toneRose
class node_social_api,node_livekit,node_audit,node_analytics,node_beta_pwa,node_celery_social,node_email,node_learner toneIndigo
```

## Components

### Learner app

- [Web app](https://github.com/git-me-harish/mentora/blob/main/frontend/src/app/(app)/chat/page.tsx): `frontend/src/app/(app)/chat/page.tsx`
- [API client](https://github.com/git-me-harish/mentora/blob/main/frontend/src/lib/api/client.ts): `frontend/src/lib/api/client.ts`

### API and identity

- [FastAPI app](https://github.com/git-me-harish/mentora/blob/main/ai_service/main.py): `ai_service/main.py`
- [Identity](https://github.com/git-me-harish/mentora/blob/main/ai_service/routers/auth.py): `ai_service/routers/auth.py`
- [Security](https://github.com/git-me-harish/mentora/blob/main/ai_service/core/security.py): `ai_service/core/security.py`
- [Observability](https://github.com/git-me-harish/mentora/blob/main/ai_service/core/observability.py): `ai_service/core/observability.py`
- [Chat API](https://github.com/git-me-harish/mentora/blob/main/ai_service/routers/chat.py): `ai_service/routers/chat.py`

### Adaptive learning

- [Adaptive API](https://github.com/git-me-harish/mentora/blob/main/ai_service/routers/adaptive.py): `ai_service/routers/adaptive.py`
- [BKT mastery](https://github.com/git-me-harish/mentora/blob/main/ai_service/engines/bkt_engine.py): `ai_service/engines/bkt_engine.py`
- [DKT mastery](https://github.com/git-me-harish/mentora/blob/main/ai_service/engines/dkt_engine.py): `ai_service/engines/dkt_engine.py`
- [Spaced repetition](https://github.com/git-me-harish/mentora/blob/main/ai_service/engines/sm2_engine.py): `ai_service/engines/sm2_engine.py`
- [Path optimizer](https://github.com/git-me-harish/mentora/blob/main/ai_service/engines/dqn_optimizer.py): `ai_service/engines/dqn_optimizer.py`
- [Recommendations](https://github.com/git-me-harish/mentora/blob/main/ai_service/services/recommendation_service.py): `ai_service/services/recommendation_service.py`

### Tutoring and content

- [Tutor orchestration](https://github.com/git-me-harish/mentora/blob/main/ai_service/pipelines/tutor_pipeline.py): `ai_service/pipelines/tutor_pipeline.py`
- [Query routing](https://github.com/git-me-harish/mentora/blob/main/ai_service/pipelines/query_router.py): `ai_service/pipelines/query_router.py`
- [Query transform](https://github.com/git-me-harish/mentora/blob/main/ai_service/pipelines/query_transform.py): `ai_service/pipelines/query_transform.py`
- [RAG retrieval](https://github.com/git-me-harish/mentora/blob/main/ai_service/services/rag_service.py): `ai_service/services/rag_service.py`
- [Embeddings](https://github.com/git-me-harish/mentora/blob/main/ai_service/services/embedding_service.py): `ai_service/services/embedding_service.py`
- **Vector store**
- [Document processing](https://github.com/git-me-harish/mentora/blob/main/ai_service/workers/document_worker.py): `ai_service/workers/document_worker.py`
- [Object storage](https://github.com/git-me-harish/mentora/blob/main/ai_service/services/storage_service.py): `ai_service/services/storage_service.py`

### Community and operations

- [Social sessions](https://github.com/git-me-harish/mentora/blob/main/ai_service/routers/study_sessions.py): `ai_service/routers/study_sessions.py`
- [Live sessions](https://github.com/git-me-harish/mentora/blob/main/ai_service/services/livekit_service.py): `ai_service/services/livekit_service.py`
- [Audit and consent](https://github.com/git-me-harish/mentora/blob/main/ai_service/services/audit_log_service.py): `ai_service/services/audit_log_service.py`
- [Learning analytics](https://github.com/git-me-harish/mentora/blob/main/ai_service/services/analytics_service.py): `ai_service/services/analytics_service.py`
- [Beta and offline](https://github.com/git-me-harish/mentora/blob/main/ai_service/routers/pwa_sync.py): `ai_service/routers/pwa_sync.py`
- [Social background tasks](https://github.com/git-me-harish/mentora/blob/main/ai_service/workers/tasks/social_tasks.py): `ai_service/workers/tasks/social_tasks.py`
- [Email delivery](https://github.com/git-me-harish/mentora/blob/main/ai_service/services/email_service.py): `ai_service/services/email_service.py`

### Other components

- **Learner**

## Connections

- Learner → Web app: uses
- Web app → API client: requests
- API client → FastAPI app: calls API
- FastAPI app → Identity: registers routes (evidence: `ai_service/main.py`)
- FastAPI app → Chat API: registers routes (evidence: `ai_service/main.py`)
- FastAPI app → Adaptive API: registers routes (evidence: `ai_service/main.py`)
- Identity → Security: uses (evidence: `ai_service/routers/auth.py`)
- Chat API → RAG retrieval: calls (evidence: `ai_service/routers/chat.py`)
- Chat API → Tutor orchestration: orchestrates
- Tutor orchestration → Query routing: routes queries (evidence: `ai_service/pipelines/tutor_pipeline.py`)
- Query routing → Query transform: reuses helper (evidence: `ai_service/pipelines/query_router.py`)
- Tutor orchestration → Query transform: transforms queries (evidence: `ai_service/pipelines/tutor_pipeline.py`)
- Tutor orchestration → RAG retrieval: retrieves context
- RAG retrieval → Embeddings: embeds queries (evidence: `ai_service/services/rag_service.py`)
- RAG retrieval → Query transform: expands queries (evidence: `ai_service/services/rag_service.py`)
- RAG retrieval → Vector store: searches vectors
- Document processing → Object storage: fetches uploads (evidence: `ai_service/workers/document_worker.py`)
- Document processing → RAG retrieval: indexes chunks (evidence: `ai_service/workers/document_worker.py`)
- Adaptive API → BKT mastery: updates mastery (evidence: `ai_service/routers/adaptive.py`)
- Adaptive API → Spaced repetition: schedules reviews (evidence: `ai_service/routers/adaptive.py`)
- Adaptive API → Path optimizer: optimizes paths
- Adaptive API → DKT mastery: estimates mastery
- Learner → Social sessions: joins sessions
- Social sessions → Live sessions: creates rooms
- Social sessions → Social background tasks: schedules tasks (evidence: `ai_service/routers/study_sessions.py`)
- FastAPI app → Observability: configures telemetry (evidence: `ai_service/main.py`)
- FastAPI app → Audit and consent: enforces compliance
- FastAPI app → Learning analytics: serves dashboards
- FastAPI app → Beta and offline: registers routes (evidence: `ai_service/main.py`)
- Social background tasks → Email delivery: sends notices
