# adhamhesham07/tutai architecture

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

- Interactive diagram: https://gitdiagram.com/adhamhesham07/tutai
- Repository: https://github.com/adhamhesham07/tutai

## Overview

TutAI is an educational chat application: a student sends a message or uploads course material, then the agent classifies the request and routes it to document analysis, question answering, quizzes, or web research. Its retrieval path uses embeddings and FAISS, while responses and synthesis use configured language models; session memory supports follow-up dialogue. The README documents these capabilities, but unsampled modules such as confidence evaluation are represented only at the documented level. Edges reflect shown calls or README relationships; optional external integrations are marked dashed where wiring is not fully shown.

Main entry points: [`agent/orchestrator.py`](https://github.com/adhamhesham07/tutai/blob/main/agent/orchestrator.py) (Agent handler), [`agent/router.py`](https://github.com/adhamhesham07/tutai/blob/main/agent/router.py) (RAG router), [`rag/rag_system.py`](https://github.com/adhamhesham07/tutai/blob/main/rag/rag_system.py) (RAG retrieval), [`llm/model_loader.py`](https://github.com/adhamhesham07/tutai/blob/main/llm/model_loader.py) (Answer generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Chat experience"]
  node_interface["Gradio interface<br/>[app.py]"]
  node_memory["Session memory<br/>[memory_tool.py]"]
end

subgraph group_agent["Agent orchestration"]
  node_agent_handler["Agent handler<br/>[orchestrator.py]"]
  node_intent["Intent classifier<br/>[intents.py]"]
  node_confidence["Confidence check<br/>[confidence.py]"]
  node_router["RAG router<br/>[router.py]"]
  node_config["Runtime settings<br/>[settings.py]"]
end

subgraph group_knowledge["Document intelligence"]
  node_parser["File parser<br/>[parser_tool.py]"]
  node_file_index["Uploaded-file index<br/>[orchestrator.py]"]
  node_rag["RAG retrieval<br/>[rag_system.py]"]
  node_vector_data[("FAISS index and chunks<br/>[faiss_index.bin]")]
end

subgraph group_generation["Models and tools"]
  node_prompts["Educational prompts"]
  node_model["Answer generation<br/>[model_loader.py]"]
  node_quiz["Quiz generator<br/>[quiz_tool.py]"]
  node_search["Web search<br/>[search_tool.py]"]
  node_synth["Web synthesis<br/>[orchestrator.py]"]
end

node_student(("Student"))
node_gemini{{"Gemini"}}
node_serpapi{{"SerpAPI"}}

node_student -->|"sends input"| node_interface
node_interface -->|"calls agent"| node_agent_handler
node_interface -->|"initializes"| node_rag
node_agent_handler -->|"classifies"| node_intent
node_agent_handler -->|"parses upload"| node_parser
node_agent_handler -->|"builds index"| node_file_index
node_agent_handler -->|"queries"| node_rag
node_agent_handler -->|"delegates questions"| node_router
node_agent_handler -->|"generates quiz"| node_quiz
node_agent_handler -->|"requests search"| node_search
node_agent_handler -->|"synthesizes search"| node_synth
node_agent_handler -->|"updates history"| node_memory
node_router -->|"retrieves context"| node_rag
node_router -->|"checks answer"| node_confidence
node_router -->|"generates answer"| node_model
node_router -->|"builds context"| node_memory
node_parser -->|"provides text"| node_file_index
node_rag -->|"loads and saves"| node_vector_data
node_file_index -->|"supplies context"| node_model
node_agent_handler -->|"generates summary"| node_model
node_agent_handler -->|"reads history"| node_memory
node_model -.->|"calls model"| node_gemini
node_intent -.->|"classifies via"| node_gemini
node_quiz -.->|"generates with"| node_gemini
node_search -.->|"searches via"| node_serpapi
node_synth -.->|"synthesizes with"| node_gemini
node_rag -->|"reads paths"| node_config
node_model -->|"reads model settings"| node_config
node_router -->|"formats prompt"| node_prompts
node_quiz -->|"formats quiz"| node_prompts

click node_interface "https://github.com/adhamhesham07/tutai/blob/main/app.py"
click node_agent_handler "https://github.com/adhamhesham07/tutai/blob/main/agent/orchestrator.py"
click node_intent "https://github.com/adhamhesham07/tutai/blob/main/agent/intents.py"
click node_confidence "https://github.com/adhamhesham07/tutai/blob/main/agent/confidence.py"
click node_router "https://github.com/adhamhesham07/tutai/blob/main/agent/router.py"
click node_parser "https://github.com/adhamhesham07/tutai/blob/main/tools/parser_tool.py"
click node_file_index "https://github.com/adhamhesham07/tutai/blob/main/agent/orchestrator.py"
click node_rag "https://github.com/adhamhesham07/tutai/blob/main/rag/rag_system.py"
click node_vector_data "https://github.com/adhamhesham07/tutai/blob/main/data/faiss_index.bin"
click node_memory "https://github.com/adhamhesham07/tutai/blob/main/tools/memory_tool.py"
click node_prompts "https://github.com/adhamhesham07/tutai/blob/main/llm/prompt_templates.py"
click node_model "https://github.com/adhamhesham07/tutai/blob/main/llm/model_loader.py"
click node_quiz "https://github.com/adhamhesham07/tutai/blob/main/tools/quiz_tool.py"
click node_search "https://github.com/adhamhesham07/tutai/blob/main/tools/search_tool.py"
click node_synth "https://github.com/adhamhesham07/tutai/blob/main/agent/orchestrator.py"
click node_config "https://github.com/adhamhesham07/tutai/blob/main/config/settings.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_interface,node_memory toneBlue
class node_agent_handler,node_intent,node_confidence,node_router,node_config toneAmber
class node_parser,node_file_index,node_rag,node_vector_data,node_serpapi toneMint
class node_prompts,node_model,node_quiz,node_search,node_synth toneRose
class node_student,node_gemini toneIndigo
```

## Components

### Chat experience

- [Gradio interface](https://github.com/adhamhesham07/tutai/blob/main/app.py): `app.py`
- [Session memory](https://github.com/adhamhesham07/tutai/blob/main/tools/memory_tool.py): `tools/memory_tool.py`

### Agent orchestration

- [Agent handler](https://github.com/adhamhesham07/tutai/blob/main/agent/orchestrator.py): `agent/orchestrator.py`
- [Intent classifier](https://github.com/adhamhesham07/tutai/blob/main/agent/intents.py): `agent/intents.py`
- [Confidence check](https://github.com/adhamhesham07/tutai/blob/main/agent/confidence.py): `agent/confidence.py`
- [RAG router](https://github.com/adhamhesham07/tutai/blob/main/agent/router.py): `agent/router.py`
- [Runtime settings](https://github.com/adhamhesham07/tutai/blob/main/config/settings.py): `config/settings.py`

### Document intelligence

- [File parser](https://github.com/adhamhesham07/tutai/blob/main/tools/parser_tool.py): `tools/parser_tool.py`
- [Uploaded-file index](https://github.com/adhamhesham07/tutai/blob/main/agent/orchestrator.py): `agent/orchestrator.py`
- [RAG retrieval](https://github.com/adhamhesham07/tutai/blob/main/rag/rag_system.py): `rag/rag_system.py`
- [FAISS index and chunks](https://github.com/adhamhesham07/tutai/blob/main/data/faiss_index.bin): `data/faiss_index.bin`

### Models and tools

- [Educational prompts](https://github.com/adhamhesham07/tutai/blob/main/llm/prompt_templates.py): `llm/prompt_templates.py`
- [Answer generation](https://github.com/adhamhesham07/tutai/blob/main/llm/model_loader.py): `llm/model_loader.py`
- [Quiz generator](https://github.com/adhamhesham07/tutai/blob/main/tools/quiz_tool.py): `tools/quiz_tool.py`
- [Web search](https://github.com/adhamhesham07/tutai/blob/main/tools/search_tool.py): `tools/search_tool.py`
- [Web synthesis](https://github.com/adhamhesham07/tutai/blob/main/agent/orchestrator.py): `agent/orchestrator.py`

### Other components

- **Student**
- **Gemini**
- **SerpAPI**

## Connections

- Student → Gradio interface: sends input (evidence: `README.md`)
- Gradio interface → Agent handler: calls agent (evidence: `app.py`)
- Gradio interface → RAG retrieval: initializes (evidence: `app.py`)
- Agent handler → Intent classifier: classifies (evidence: `agent/orchestrator.py`)
- Agent handler → File parser: parses upload (evidence: `agent/orchestrator.py`)
- Agent handler → Uploaded-file index: builds index (evidence: `agent/orchestrator.py`)
- Agent handler → RAG retrieval: queries (evidence: `agent/orchestrator.py`)
- Agent handler → RAG router: delegates questions (evidence: `agent/orchestrator.py`)
- Agent handler → Quiz generator: generates quiz (evidence: `agent/orchestrator.py`)
- Agent handler → Web search: requests search (evidence: `agent/orchestrator.py`)
- Agent handler → Web synthesis: synthesizes search (evidence: `agent/orchestrator.py`)
- Agent handler → Session memory: updates history (evidence: `agent/orchestrator.py`)
- RAG router → RAG retrieval: retrieves context (evidence: `agent/router.py`)
- RAG router → Confidence check: checks answer (evidence: `agent/router.py`)
- RAG router → Answer generation: generates answer (evidence: `agent/router.py`)
- RAG router → Session memory: builds context (evidence: `agent/router.py`)
- File parser → Uploaded-file index: provides text (evidence: `agent/orchestrator.py`)
- RAG retrieval → FAISS index and chunks: loads and saves (evidence: `rag/rag_system.py`)
- Uploaded-file index → Answer generation: supplies context (evidence: `agent/orchestrator.py`)
- Agent handler → Answer generation: generates summary (evidence: `agent/orchestrator.py`)
- Agent handler → Session memory: reads history (evidence: `agent/orchestrator.py`)
- Answer generation → Gemini: calls model (evidence: `llm/model_loader.py`)
- Intent classifier → Gemini: classifies via (evidence: `agent/intents.py`)
- Quiz generator → Gemini: generates with (evidence: `tools/quiz_tool.py`)
- Web search → SerpAPI: searches via (evidence: `tools/search_tool.py`)
- Web synthesis → Gemini: synthesizes with (evidence: `agent/orchestrator.py`)
- RAG retrieval → Runtime settings: reads paths (evidence: `rag/rag_system.py`)
- Answer generation → Runtime settings: reads model settings (evidence: `llm/model_loader.py`)
- RAG router → Educational prompts: formats prompt (evidence: `agent/router.py`)
- Quiz generator → Educational prompts: formats quiz (evidence: `tools/quiz_tool.py`)