# priyamakeshwari/teachgpt architecture

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

- Interactive diagram: https://gitdiagram.com/priyamakeshwari/teachgpt
- Repository: https://github.com/priyamakeshwari/teachgpt

## Overview

##### TeachGPT’s Type and Purpose
- Type: An open‐source AI‐Powered Virtual Tutor platform implemented in Python.
- Purpose: Ingest educational documents, build a retrieval‐augmented knowledge store, power an interactive LLM‐based tutoring agent with speech I/O and gamification.

##### File Structure
- builder.py & config.py: Data‐preparation pipeline for creating/updating the vector database.
- db/…: Chroma (or similar) vector store files and a SQLite metadata store.
- documents/: Source PDFs (e.g., Tom Mitchell’s ML book).
- main.py: Orchestrates the runtime service—loads config, starts the tutor agent loop.
- requirements.txt: Specifies LLM, embedding, ASR/TTS, and gamification libs.

##### README Insights
- No client‐UI folder—service likely exposes a CLI or HTTP API.
- Calls out LLM, speech recognition integration, and gamification.

##### Core Components & Their Interactions
a. Document Ingestion & Vector Store Builder
– Inputs: PDFs from documents/
– Process: builder.py reads text, computes embeddings, writes to db/(uuid)… bins + chroma.sqlite3
– Config: config.py defines model endpoints, DB paths.
b. Vector Database (Chroma + SQLite)
– Stores high‐dim embeddings and metadata for retrieval.
c. LLM Tutor Service (main.py)
– Loads vector store + LLM model (OpenAI/in‐house)
– Exposes interaction loop or REST endpoints.
d. Speech Pipeline
– ASR Module: Speech → Text
– TTS Module: Response Text → Speech
e. Gamification Engine
– Tracks user progress, awards points/badges, updates user state.
f. External Clients
– CLI, Web front‐end, or other consumer apps sending/receiving JSON or audio streams.

##### Architectural Patterns & Design Principles
- Modular “Pipeline” for data prep (builder → db).
- Retrieval‐Augmented Generation (RAG) pattern: Vector DB + LLM.
- Pluggable speech I/O and gamification modules following Dependency Injection via config.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        DOC["Source Documents<br/>(documents/)"]:::storage
        BUILDER["Data Prep Pipeline<br/>(builder.py)"]:::compute
        DB["Vector Database<br/>(Chroma + SQLite)"]:::storage
    end

    %% Service Layer
    subgraph "Service Layer"
        CONFIG["Configuration Module<br/>(config.py)"]:::crosscut
        MAIN["LLM Tutor Service<br/>(main.py)"]:::compute
        ASR["ASR Module"]:::compute
        TTS["TTS Module"]:::compute
        GAM["Gamification Engine"]:::crosscut
    end

    %% Client Layer
    subgraph "Client Layer"
        CLIENT["External Clients<br/>(CLI/Web)"]:::external
    end

    %% Flows
    DOC -->|"PDFs"| BUILDER
    BUILDER -->|"Embedding Vectors"| DB
    CONFIG --> MAIN
    DB -->|"Retrieval Data"| MAIN
    CLIENT -->|"Audio Stream<br/>(User Speech)"| ASR
    ASR -->|"Text Query"| MAIN
    CLIENT -->|"Text Query"| MAIN
    MAIN -->|"Response Text"| GAM
    GAM -->|"User Profile Updates"| DB
    MAIN -->|"Response Text"| TTS
    TTS -->|"Audio Stream"| CLIENT

    %% Click Events
    click DOC "https://github.com/priyamakeshwari/teachgpt/tree/main/documents/"
    click BUILDER "https://github.com/priyamakeshwari/teachgpt/blob/main/builder.py"
    click DB "https://github.com/priyamakeshwari/teachgpt/tree/main/db/"
    click CONFIG "https://github.com/priyamakeshwari/teachgpt/blob/main/config.py"
    click MAIN "https://github.com/priyamakeshwari/teachgpt/blob/main/main.py"
    click CLIENT "https://github.com/priyamakeshwari/teachgpt/blob/main/requirements.txt"

    %% Styles
    classDef storage fill:#cce5ff,stroke:#999,stroke-width:1px
    classDef compute fill:#ccffcc,stroke:#999,stroke-width:1px
    classDef external fill:#ffddcc,stroke:#999,stroke-width:1px
    classDef crosscut fill:#e5ccff,stroke:#999,stroke-width:1px
```
