# rehab-hamdy/agentic-ai-tutor architecture

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

- Interactive diagram: https://gitdiagram.com/rehab-hamdy/agentic-ai-tutor
- Repository: https://github.com/rehab-hamdy/agentic-ai-tutor

## Overview

GenT is a web-based AI tutor and assessment platform. Students authenticate, organize course documents by subject, ask citation-grounded questions in chat, and take quizzes generated from those materials; they can also review progress. The documented product spans document ingestion and knowledge-graph construction, hybrid retrieval and answer generation, and quiz generation and validation. The graph shows these major capabilities plus the frontend, ASP.NET API, and persistence layers. Some AI-service and backend wiring is not shown in the sampled source, so those cross-service links are marked unverified.

Main entry points: [`ai_service/app/main.py`](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/main.py) (AI service API), [`Frontend/src/lib/apiClient.ts`](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Frontend/src/lib/apiClient.ts) (API client), [`Backend/AgenticAITutor/AgenticAITutor/Data/AppDbContext.cs`](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Data/AppDbContext.cs) (Relational data), [`ai_service/app/rag_service.py`](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/rag_service.py) (RAG answering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Student web app"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_api_client["API client<br/>[apiClient.ts]"]
  node_chat_ui["Chat experience<br/>[Chat.tsx]"]
  node_quiz_ui["Quiz experience<br/>[ActiveQuiz.tsx]"]
  node_auth_ui["Authentication UI<br/>[AuthContext.tsx]"]
end

subgraph group_api["Application backend"]
  node_api_host["ASP.NET API<br/>[Program.cs]"]
  node_auth["Authentication<br/>[AuthService.cs]"]
  node_documents["Document management"]
  node_file_storage["Uploaded files"]
  node_chat_sessions["Chat sessions"]
  node_chat_messages["Chat orchestration"]
  node_relational_store[("Relational data<br/>[AppDbContext.cs]")]
  node_quiz_backend["Quiz management<br/>[QuizController.cs]"]
  node_quiz_jobs["Quiz processing"]
  node_analytics["Learning analytics"]
end

subgraph group_tutor["AI tutoring"]
  node_ai_service["AI service API<br/>[main.py]"]
  node_ingestion["Document chunking<br/>[kg_pipeline.py]"]
  node_rag_service["RAG answering<br/>[rag_service.py]"]
  node_embeddings["Text embeddings<br/>[embedding.py]"]
  node_vector_store[("Vector retrieval<br/>[vector_store.py]")]
  node_knowledge_graph[("Knowledge graph<br/>[kg_service.py]")]
  node_llm["Language model<br/>[llm.py]"]
end

subgraph group_assessment["Assessment AI"]
  node_quiz_generation["Quiz generation<br/>[quiz_generator.py]"]
  node_quiz_routes["Quiz API routes"]
end

node_student(("Student"))
node_external_search["Web search"]
node_voice["Speech services"]

node_student -->|"uses"| node_webapp
node_webapp -->|"routes requests"| node_api_client
node_chat_ui -.->|"requests data"| node_api_client
node_quiz_ui -.->|"requests data"| node_api_client
node_auth_ui -->|"authenticates through"| node_api_client
node_api_client -.->|"calls"| node_api_host
node_api_host -->|"registers service"| node_auth
node_api_host -->|"configures"| node_relational_store
node_documents -.->|"stores uploads"| node_file_storage
node_chat_sessions -.->|"persists sessions"| node_relational_store
node_chat_messages -.->|"posts chat request"| node_ai_service
node_chat_messages -.->|"persists messages"| node_relational_store
node_ai_service -.->|"processes documents"| node_ingestion
node_ingestion -.->|"builds graph"| node_knowledge_graph
node_ai_service -.->|"dispatches answers"| node_rag_service
node_rag_service -->|"embeds query"| node_embeddings
node_rag_service -->|"retrieves chunks"| node_vector_store
node_rag_service -->|"generates answer"| node_llm
node_ai_service -.->|"retrieves concepts"| node_knowledge_graph
node_ai_service -.->|"augments answers"| node_external_search
node_ai_service -.->|"supports speech"| node_voice
node_quiz_routes -->|"dispatches generation"| node_quiz_generation
node_quiz_backend -.->|"schedules processing"| node_quiz_jobs
node_quiz_jobs -.->|"requests quiz work"| node_quiz_routes
node_quiz_backend -.->|"persists attempts"| node_relational_store
node_analytics -.->|"reads progress"| node_relational_store
node_student -->|"asks questions"| node_chat_ui
node_student -->|"takes quizzes"| node_quiz_ui

click node_webapp "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Frontend/src/app/App.tsx"
click node_api_client "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Frontend/src/lib/apiClient.ts"
click node_chat_ui "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Frontend/src/app/pages/Chat.tsx"
click node_quiz_ui "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Frontend/src/app/pages/ActiveQuiz.tsx"
click node_auth_ui "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Frontend/src/context/AuthContext.tsx"
click node_api_host "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Program.cs"
click node_auth "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Services/Auth/AuthService.cs"
click node_documents "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Controllers/DocumentController.cs"
click node_file_storage "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Services/Storage/LocalFileStorageService.cs"
click node_chat_sessions "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Services/ChatSession/ChatSessionService.cs"
click node_chat_messages "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Services/ChatMessage/ChatMessageService.cs"
click node_relational_store "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Data/AppDbContext.cs"
click node_ai_service "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/main.py"
click node_ingestion "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/kg_pipeline.py"
click node_rag_service "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/rag_service.py"
click node_embeddings "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/embedding.py"
click node_vector_store "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/vector_store.py"
click node_knowledge_graph "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/kg_service.py"
click node_llm "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/llm.py"
click node_quiz_generation "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/quiz/quiz_generator.py"
click node_quiz_routes "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/quiz/quiz_generate_router.py"
click node_quiz_backend "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Controllers/QuizController.cs"
click node_quiz_jobs "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/BackgroundJobs/QuizGenerationJob.cs"
click node_analytics "https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Controllers/AnalyticsController.cs"

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,node_chat_ui,node_quiz_ui,node_auth_ui toneBlue
class node_api_host,node_auth,node_documents,node_file_storage,node_chat_sessions,node_chat_messages,node_relational_store,node_quiz_backend,node_quiz_jobs,node_analytics toneAmber
class node_ai_service,node_ingestion,node_rag_service,node_embeddings,node_vector_store,node_knowledge_graph,node_llm toneMint
class node_quiz_generation,node_quiz_routes toneRose
class node_student,node_external_search,node_voice toneIndigo
```

## Components

### Student web app

- [Web application](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Frontend/src/app/App.tsx): `Frontend/src/app/App.tsx`
- [API client](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Frontend/src/lib/apiClient.ts): `Frontend/src/lib/apiClient.ts`
- [Chat experience](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Frontend/src/app/pages/Chat.tsx): `Frontend/src/app/pages/Chat.tsx`
- [Quiz experience](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Frontend/src/app/pages/ActiveQuiz.tsx): `Frontend/src/app/pages/ActiveQuiz.tsx`
- [Authentication UI](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Frontend/src/context/AuthContext.tsx): `Frontend/src/context/AuthContext.tsx`

### Application backend

- [ASP.NET API](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Program.cs): `Backend/AgenticAITutor/AgenticAITutor/Program.cs`
- [Authentication](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Services/Auth/AuthService.cs): `Backend/AgenticAITutor/AgenticAITutor/Services/Auth/AuthService.cs`
- [Document management](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Controllers/DocumentController.cs): `Backend/AgenticAITutor/AgenticAITutor/Controllers/DocumentController.cs`
- [Uploaded files](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Services/Storage/LocalFileStorageService.cs): `Backend/AgenticAITutor/AgenticAITutor/Services/Storage/LocalFileStorageService.cs`
- [Chat sessions](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Services/ChatSession/ChatSessionService.cs): `Backend/AgenticAITutor/AgenticAITutor/Services/ChatSession/ChatSessionService.cs`
- [Chat orchestration](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Services/ChatMessage/ChatMessageService.cs): `Backend/AgenticAITutor/AgenticAITutor/Services/ChatMessage/ChatMessageService.cs`
- [Relational data](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Data/AppDbContext.cs): `Backend/AgenticAITutor/AgenticAITutor/Data/AppDbContext.cs`
- [Quiz management](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Controllers/QuizController.cs): `Backend/AgenticAITutor/AgenticAITutor/Controllers/QuizController.cs`
- [Quiz processing](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/BackgroundJobs/QuizGenerationJob.cs): `Backend/AgenticAITutor/AgenticAITutor/BackgroundJobs/QuizGenerationJob.cs`
- [Learning analytics](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/Backend/AgenticAITutor/AgenticAITutor/Controllers/AnalyticsController.cs): `Backend/AgenticAITutor/AgenticAITutor/Controllers/AnalyticsController.cs`

### AI tutoring

- [AI service API](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/main.py): `ai_service/app/main.py`
- [Document chunking](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/kg_pipeline.py): `ai_service/app/kg_pipeline.py`
- [RAG answering](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/rag_service.py): `ai_service/app/rag_service.py`
- [Text embeddings](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/embedding.py): `ai_service/app/embedding.py`
- [Vector retrieval](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/vector_store.py): `ai_service/app/vector_store.py`
- [Knowledge graph](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/kg_service.py): `ai_service/app/kg_service.py`
- [Language model](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/llm.py): `ai_service/app/llm.py`

### Assessment AI

- [Quiz generation](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/quiz/quiz_generator.py): `ai_service/app/quiz/quiz_generator.py`
- [Quiz API routes](https://github.com/rehab-hamdy/agentic-ai-tutor/blob/main/ai_service/app/quiz/quiz_generate_router.py): `ai_service/app/quiz/quiz_generate_router.py`

### Other components

- **Student**
- **Web search**
- **Speech services**

## Connections

- Student → Web application: uses (evidence: `README.md`)
- Web application → API client: routes requests (evidence: `Frontend/src/app/App.tsx`)
- Chat experience → API client: requests data
- Quiz experience → API client: requests data
- Authentication UI → API client: authenticates through
- API client → ASP.NET API: calls
- ASP.NET API → Authentication: registers service (evidence: `Backend/AgenticAITutor/AgenticAITutor/Program.cs`)
- ASP.NET API → Relational data: configures (evidence: `Backend/AgenticAITutor/AgenticAITutor/Program.cs`)
- Document management → Uploaded files: stores uploads
- Chat sessions → Relational data: persists sessions
- Chat orchestration → AI service API: posts chat request
- Chat orchestration → Relational data: persists messages
- AI service API → Document chunking: processes documents
- Document chunking → Knowledge graph: builds graph
- AI service API → RAG answering: dispatches answers
- RAG answering → Text embeddings: embeds query (evidence: `ai_service/app/rag_service.py`)
- RAG answering → Vector retrieval: retrieves chunks (evidence: `ai_service/app/rag_service.py`)
- RAG answering → Language model: generates answer (evidence: `ai_service/app/rag_service.py`)
- AI service API → Knowledge graph: retrieves concepts
- AI service API → Web search: augments answers
- AI service API → Speech services: supports speech
- Quiz API routes → Quiz generation: dispatches generation (evidence: `ai_service/app/quiz/quiz_generate_router.py`)
- Quiz management → Quiz processing: schedules processing
- Quiz processing → Quiz API routes: requests quiz work
- Quiz management → Relational data: persists attempts
- Learning analytics → Relational data: reads progress
- Student → Chat experience: asks questions (evidence: `README.md`)
- Student → Quiz experience: takes quizzes (evidence: `README.md`)