# hqanhh/edugpt architecture

> Architecture diagram of the GitHub repository hqanhh/edugpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hqanhh/edugpt
- Repository: https://github.com/hqanhh/edugpt

## Overview

##### Main Components
- User Interface (UI)
- Gradio web interface launched by src/run.py
- Orchestration Layer
- run.py: ties UI inputs to the agent pipeline
- Agent Modules
- Role-playing Agents (syllabus designers)
– generating_syllabus.py
- Instructor Agent
– teaching_agent.py
- Core Services
- LangChain abstraction layer
- OpenAI LLM API (external service)
- Configuration & Environment
- .env (OPENAI_API_KEY)
- pyproject.toml / requirements.txt / setup.py

##### Relationships & Data Flows
1) User opens the Gradio UI (run.py).
2) User submits “desired learning topics.”
3) run.py invokes the Agent Initialization:
– Agents are instantiated via LangChain wrappers.
4) Role-playing Agents exchange messages:
– generating_syllabus.py orchestrates a two-agent dialogue.
5) Syllabus Generation:
– The conversation history is passed to OpenAI LLM to produce a structured syllabus.
6) Instructor Agent Activation:
– teaching_agent.py receives the syllabus and user questions.
– It uses OpenAI LLM calls to generate teaching responses.
7) Gradio UI updates live with syllabus then Q&A from the Instructor Agent.

##### Architectural Patterns & Principles
- Modular Agent Pipeline: each stage is its own Python module.
- External API Integration: all LLM calls go through LangChain → OpenAI.
- Separation of Concerns:
- UI (Gradio) vs. Orchestration (run.py) vs. Domain Logic (agents).
- Configuration-driven: environment variables & config files control API keys and dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Python Application"
        UI["Gradio UI"]:::ui
        Orch["run.py<br/>Orchestrator"]:::orchestration
        RP["Role-playing Agents<br/>generating_syllabus.py"]:::agent
        IA["Instructor Agent<br/>teaching_agent.py"]:::agent
        Config["Configuration<br/>(.env, pyproject.toml,<br/>requirements.txt, setup.py)"]:::config
    end

    subgraph "External Services"
        LLM["OpenAI LLM API<br/>(via LangChain)"]:::external
    end

    subgraph "Dev Artifacts"
        NB["Jupyter Notebook<br/>EduGPT.ipynb"]:::dev
    end

    UI -->|"user input"| Orch
    Orch -->|"instantiate agents"| RP
    RP -->|"syllabus prompt"| LLM
    LLM -->|"syllabus JSON"| IA
    IA -->|"teaching response"| UI

    Config -.-> Orch
    Config -.-> LLM

    click Orch "https://github.com/hqanhh/edugpt/blob/main/src/run.py"
    click RP "https://github.com/hqanhh/edugpt/blob/main/src/generating_syllabus.py"
    click IA "https://github.com/hqanhh/edugpt/blob/main/src/teaching_agent.py"
    click NB "https://github.com/hqanhh/edugpt/blob/main/src/EduGPT.ipynb"
    click Config "https://github.com/hqanhh/edugpt/blob/main/.env"
    click Config "https://github.com/hqanhh/edugpt/blob/main/pyproject.toml"
    click Config "https://github.com/hqanhh/edugpt/blob/main/requirements.txt"
    click Config "https://github.com/hqanhh/edugpt/blob/main/setup.py"

    classDef ui fill:#cee7ff,stroke:#0066cc,color:#004080;
    classDef orchestration fill:#d5efd5,stroke:#2d862d,color:#1a4f1a;
    classDef agent fill:#ffe5b4,stroke:#ff8c00,color:#b35200;
    classDef external fill:#fddcdc,stroke:#cc0000,color:#800000;
    classDef config fill:#f0f0f0,stroke:#666666,color:#333333;
    classDef dev fill:#f3e5ff,stroke:#800080,color:#4b0082;
```
