# ashwarygupta/vidyai architecture

> Architecture diagram of the GitHub repository ashwarygupta/vidyai, 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/ashwarygupta/vidyai
- Repository: https://github.com/ashwarygupta/vidyai

## Overview

VidyAI serves exam aspirants through a student portal and exposes the same learning capabilities to partners through an MCP API and partner-management portal. The student workflow spans doubt solving, revision, planning, practice tests, progress, syllabus and learning content; video processing also runs asynchronously. The README documents these capabilities, while sampled source confirms the API’s router registration, some retention and content-processing behavior, and partner-client requests. Several service-to-router details and integrations are documented but unsampled, so uncertain internal wiring is omitted.

Main entry points: [`services/api/main.py`](https://github.com/ashwarygupta/vidyai/blob/main/services/api/main.py) (FastAPI gateway), [`apps/web/lib/api/client.ts`](https://github.com/ashwarygupta/vidyai/blob/main/apps/web/lib/api/client.ts) (Web API client), [`services/api/services`](https://github.com/ashwarygupta/vidyai/tree/main/services/api/services) (Learning services), [`services/api/routers/mcp.py`](https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/mcp.py) (MCP tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_student["Student learning"]
  node_web_portal["Student portal"]
  node_web_api["Web API client<br/>[client.ts]"]
  node_tutor_ui["AI tutor<br/>[page.tsx]"]
  node_revision_ui["Revision<br/>[page.tsx]"]
  node_planner_ui["Study planner<br/>[page.tsx]"]
  node_content_ui["Study content<br/>[page.tsx]"]
  node_progress_ui["Progress<br/>[page.tsx]"]
end

subgraph group_partner["Partner access"]
  node_partner_portal["Partner portal"]
  node_partner_client["Partner API client<br/>[partner-client.ts]"]
  node_embed_sdk["Embed SDK<br/>[index.ts]"]
end

subgraph group_api["API features"]
  node_api_gateway["FastAPI gateway<br/>[main.py]"]
  node_tutor_api["Tutor endpoint<br/>[tutor.py]"]
  node_retention_api["Retention endpoint<br/>[retention.py]"]
  node_planner_api["Planner endpoint<br/>[planner.py]"]
  node_mcq_api["Test endpoints<br/>[mcq.py]"]
  node_content_api["Content endpoint<br/>[content.py]"]
  node_progress_api["Progress endpoint<br/>[progress.py]"]
  node_knowledge_api["Knowledge endpoint<br/>[knowledge.py]"]
  node_syllabus_api["Syllabus endpoint<br/>[syllabus.py]"]
  node_mcp_api["MCP tools<br/>[mcp.py]"]
  node_domain_services["Learning services"]
  node_knowledge_index["PageIndex search"]
end

subgraph group_async["Async processing"]
  node_video_worker["Video worker<br/>[video_worker.py]"]
  node_scheduler_worker["Revision scheduler"]
end

subgraph group_data["Persistence"]
  node_supabase[("Supabase")]
end

node_student_actor(("Student"))
node_partner_actor(("Partner operator"))
node_partner_agent(("Partner LLM agent"))

node_student_actor -->|"uses"| node_web_portal
node_web_portal -->|"requests features"| node_web_api
node_tutor_ui -->|"calls API"| node_web_api
node_revision_ui -->|"calls API"| node_web_api
node_planner_ui -->|"calls API"| node_web_api
node_content_ui -->|"calls API"| node_web_api
node_progress_ui -->|"calls API"| node_web_api
node_web_api -->|"HTTP requests"| node_api_gateway
node_api_gateway -->|"mounts route"| node_tutor_api
node_api_gateway -->|"mounts route"| node_retention_api
node_api_gateway -->|"mounts route"| node_planner_api
node_api_gateway -->|"mounts route"| node_mcq_api
node_api_gateway -->|"mounts route"| node_content_api
node_api_gateway -->|"mounts route"| node_progress_api
node_api_gateway -->|"mounts route"| node_knowledge_api
node_api_gateway -->|"mounts route"| node_syllabus_api
node_api_gateway -->|"mounts route"| node_mcp_api
node_tutor_api -.->|"retrieves context"| node_knowledge_index
node_mcp_api -.->|"delegates features"| node_domain_services
node_partner_actor -->|"manages account"| node_partner_portal
node_partner_portal -->|"uses"| node_partner_client
node_partner_client -->|"partner requests"| node_api_gateway
node_partner_agent -->|"calls tools"| node_mcp_api
node_embed_sdk -.->|"requests embedded features"| node_api_gateway
node_retention_api -.->|"handles retention"| node_domain_services
node_planner_api -.->|"handles planning"| node_domain_services
node_mcq_api -.->|"handles tests"| node_domain_services
node_content_api -.->|"handles content"| node_domain_services
node_video_worker -->|"updates video records"| node_supabase
node_scheduler_worker -->|"schedules revision cards"| node_supabase
node_knowledge_index -->|"reads and stores indexes"| node_supabase
node_domain_services -.->|"persists learning state"| node_supabase

click node_web_portal "https://github.com/ashwarygupta/vidyai/tree/main/apps/web/app/(dashboard)/dashboard"
click node_web_api "https://github.com/ashwarygupta/vidyai/blob/main/apps/web/lib/api/client.ts"
click node_tutor_ui "https://github.com/ashwarygupta/vidyai/blob/main/apps/web/app/(dashboard)/dashboard/tutor/page.tsx"
click node_revision_ui "https://github.com/ashwarygupta/vidyai/blob/main/apps/web/app/(dashboard)/dashboard/revision/page.tsx"
click node_planner_ui "https://github.com/ashwarygupta/vidyai/blob/main/apps/web/app/(dashboard)/dashboard/planner/page.tsx"
click node_content_ui "https://github.com/ashwarygupta/vidyai/blob/main/apps/web/app/(dashboard)/dashboard/content/page.tsx"
click node_progress_ui "https://github.com/ashwarygupta/vidyai/blob/main/apps/web/app/(dashboard)/dashboard/progress/page.tsx"
click node_api_gateway "https://github.com/ashwarygupta/vidyai/blob/main/services/api/main.py"
click node_tutor_api "https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/tutor.py"
click node_retention_api "https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/retention.py"
click node_planner_api "https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/planner.py"
click node_mcq_api "https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/mcq.py"
click node_content_api "https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/content.py"
click node_progress_api "https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/progress.py"
click node_knowledge_api "https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/knowledge.py"
click node_syllabus_api "https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/syllabus.py"
click node_mcp_api "https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/mcp.py"
click node_domain_services "https://github.com/ashwarygupta/vidyai/tree/main/services/api/services"
click node_knowledge_index "https://github.com/ashwarygupta/vidyai/blob/main/services/api/services/knowledge_service.py"
click node_partner_portal "https://github.com/ashwarygupta/vidyai/tree/main/apps/partner/app/(portal)"
click node_partner_client "https://github.com/ashwarygupta/vidyai/blob/main/apps/partner/lib/api/partner-client.ts"
click node_embed_sdk "https://github.com/ashwarygupta/vidyai/blob/main/packages/embed-sdk/src/index.ts"
click node_video_worker "https://github.com/ashwarygupta/vidyai/blob/main/services/api/workers/video_worker.py"
click node_scheduler_worker "https://github.com/ashwarygupta/vidyai/blob/main/services/api/workers/scheduler_worker.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_portal,node_web_api,node_tutor_ui,node_revision_ui,node_planner_ui,node_content_ui,node_progress_ui toneBlue
class node_partner_portal,node_partner_client,node_embed_sdk toneAmber
class node_api_gateway,node_tutor_api,node_retention_api,node_planner_api,node_mcq_api,node_content_api,node_progress_api,node_knowledge_api,node_syllabus_api,node_mcp_api,node_domain_services,node_knowledge_index toneMint
class node_video_worker,node_scheduler_worker toneRose
class node_supabase,node_student_actor,node_partner_actor,node_partner_agent toneIndigo
```

## Components

### Student learning

- [Student portal](https://github.com/ashwarygupta/vidyai/tree/main/apps/web/app/(dashboard)/dashboard): `apps/web/app/(dashboard)/dashboard`
- [Web API client](https://github.com/ashwarygupta/vidyai/blob/main/apps/web/lib/api/client.ts): `apps/web/lib/api/client.ts`
- [AI tutor](https://github.com/ashwarygupta/vidyai/blob/main/apps/web/app/(dashboard)/dashboard/tutor/page.tsx): `apps/web/app/(dashboard)/dashboard/tutor/page.tsx`
- [Revision](https://github.com/ashwarygupta/vidyai/blob/main/apps/web/app/(dashboard)/dashboard/revision/page.tsx): `apps/web/app/(dashboard)/dashboard/revision/page.tsx`
- [Study planner](https://github.com/ashwarygupta/vidyai/blob/main/apps/web/app/(dashboard)/dashboard/planner/page.tsx): `apps/web/app/(dashboard)/dashboard/planner/page.tsx`
- [Study content](https://github.com/ashwarygupta/vidyai/blob/main/apps/web/app/(dashboard)/dashboard/content/page.tsx): `apps/web/app/(dashboard)/dashboard/content/page.tsx`
- [Progress](https://github.com/ashwarygupta/vidyai/blob/main/apps/web/app/(dashboard)/dashboard/progress/page.tsx): `apps/web/app/(dashboard)/dashboard/progress/page.tsx`

### Partner access

- [Partner portal](https://github.com/ashwarygupta/vidyai/tree/main/apps/partner/app/(portal)): `apps/partner/app/(portal)`
- [Partner API client](https://github.com/ashwarygupta/vidyai/blob/main/apps/partner/lib/api/partner-client.ts): `apps/partner/lib/api/partner-client.ts`
- [Embed SDK](https://github.com/ashwarygupta/vidyai/blob/main/packages/embed-sdk/src/index.ts): `packages/embed-sdk/src/index.ts`

### API features

- [FastAPI gateway](https://github.com/ashwarygupta/vidyai/blob/main/services/api/main.py): `services/api/main.py`
- [Tutor endpoint](https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/tutor.py): `services/api/routers/tutor.py`
- [Retention endpoint](https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/retention.py): `services/api/routers/retention.py`
- [Planner endpoint](https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/planner.py): `services/api/routers/planner.py`
- [Test endpoints](https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/mcq.py): `services/api/routers/mcq.py`
- [Content endpoint](https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/content.py): `services/api/routers/content.py`
- [Progress endpoint](https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/progress.py): `services/api/routers/progress.py`
- [Knowledge endpoint](https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/knowledge.py): `services/api/routers/knowledge.py`
- [Syllabus endpoint](https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/syllabus.py): `services/api/routers/syllabus.py`
- [MCP tools](https://github.com/ashwarygupta/vidyai/blob/main/services/api/routers/mcp.py): `services/api/routers/mcp.py`
- [Learning services](https://github.com/ashwarygupta/vidyai/tree/main/services/api/services): `services/api/services`
- [PageIndex search](https://github.com/ashwarygupta/vidyai/blob/main/services/api/services/knowledge_service.py): `services/api/services/knowledge_service.py`

### Async processing

- [Video worker](https://github.com/ashwarygupta/vidyai/blob/main/services/api/workers/video_worker.py): `services/api/workers/video_worker.py`
- [Revision scheduler](https://github.com/ashwarygupta/vidyai/blob/main/services/api/workers/scheduler_worker.py): `services/api/workers/scheduler_worker.py`

### Persistence

- **Supabase**

### Other components

- **Student**
- **Partner operator**
- **Partner LLM agent**

## Connections

- Student → Student portal: uses
- Student portal → Web API client: requests features
- AI tutor → Web API client: calls API
- Revision → Web API client: calls API
- Study planner → Web API client: calls API
- Study content → Web API client: calls API
- Progress → Web API client: calls API
- Web API client → FastAPI gateway: HTTP requests
- FastAPI gateway → Tutor endpoint: mounts route
- FastAPI gateway → Retention endpoint: mounts route
- FastAPI gateway → Planner endpoint: mounts route
- FastAPI gateway → Test endpoints: mounts route
- FastAPI gateway → Content endpoint: mounts route
- FastAPI gateway → Progress endpoint: mounts route
- FastAPI gateway → Knowledge endpoint: mounts route
- FastAPI gateway → Syllabus endpoint: mounts route
- FastAPI gateway → MCP tools: mounts route
- Tutor endpoint → PageIndex search: retrieves context
- MCP tools → Learning services: delegates features
- Partner operator → Partner portal: manages account
- Partner portal → Partner API client: uses
- Partner API client → FastAPI gateway: partner requests
- Partner LLM agent → MCP tools: calls tools
- Embed SDK → FastAPI gateway: requests embedded features
- Retention endpoint → Learning services: handles retention
- Planner endpoint → Learning services: handles planning
- Test endpoints → Learning services: handles tests
- Content endpoint → Learning services: handles content
- Video worker → Supabase: updates video records
- Revision scheduler → Supabase: schedules revision cards
- PageIndex search → Supabase: reads and stores indexes
- Learning services → Supabase: persists learning state