# theexplainthis/chatgpt-ai-english-tutor architecture

> Architecture diagram of the GitHub repository theexplainthis/chatgpt-ai-english-tutor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theexplainthis/chatgpt-ai-english-tutor
- Repository: https://github.com/theexplainthis/chatgpt-ai-english-tutor

## Overview

##### Project Type and Purpose
- This is a Python-based AI tutoring application that leverages multiple third-party services—namely, OpenAI’s GPT-3.5 for conversational responses, Whisper for audio processing, and Google Text-To-Speech for converting text back to speech.
- The system integrates with the LINE messaging platform (using its webhook mechanism) so that students can interact with an AI teacher. In addition, it records and “reflects” on student performance via periodic reviews.
- Its lightweight storage appears to be handled via TinyDB for student records or logs.

##### File Structure Analysis
- Top-Level Files:
– LICENSE and README.md: General project metadata.
– main.py: Likely the entry point that orchestrates the overall process.
– requirements.txt: Lists Python dependencies.
- Directories:
– demo: Contains demo assets (e.g., screenshots) that visually communicate the product.
– files: May hold additional or temporary files.
– src: Contains core modules:
- audio.py: Likely handles audio capture, possibly integrating with Whisper to process student audio.
- models.py: Might define any internal data models, perhaps representing conversation or learning states.
- speech.py: Presumably processes text-to-speech and speech response logic using Google TTS.
- storage.py: Handles saving and retrieving study records, interfacing with TinyDB.
– tinydb: Likely holds database data or supportive files for the TinyDB lightweight database.
- The structure indicates a modular design where each file in the src directory is responsible for a specific functional area.

##### Key Components
a. User/Client Layer:
– LINE Messaging Client: The student interacts with the AI tutor through the LINE app.
b. Webhook/API Layer:
– LINE Developer’s Messaging API: Represents inbound interactions, where the LINE platform sends messages to your service via the /callback endpoint.
– main.py: Acts as the central controller that accepts these requests, processes them, and dispatches the tasks.
c. Core Functional Modules:
– Audio Module (audio.py): Converts incoming audio messages (or voice inputs via LINE) into a format processed by Whisper.
– Speech Module (speech.py): Manages text-to-speech conversion using Google Cloud’s Text-To-Speech API.
– Models Module (models.py): Holds conversational models or business logic for generating AI responses. This module connects with OpenAI’s GPT-3.5.
– Storage Module (storage.py): Persists student data, historical interactions, or performance records using TinyDB.
d. External Services:
– OpenAI GPT-3.5 API: For generating tutor responses.
– Google Text-To-Speech API: For producing audio feedback.
– Whisper API (or library integration): For audio-to-text conversion.
e. Supporting Infrastructure:
– Environment Setup: Secrets (API keys, tokens) and configuration settings are loaded into the application (e.g., via Replit’s Secrets or a JSON credential file).
– CronJob Service: An external service (cron-job.org) periodically pings the server to keep the Replit instance active.

##### Relationships and Interactions
– How incoming messages flow from the LINE Messaging Client to your webhook endpoint (/callback) handled by main.py.
– From main.py, delineate separate calls:
- To the audio module for converting audio inputs if needed.
- To the models module which calls the GPT-3.5 API to generate responses.
- To the speech module to convert text responses into audible feedback via the Google TTS API.
– Data storage interactions showing how student data or conversation logs are stored/retrieved via storage.py and TinyDB.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Different modules in the src directory handle distinct tasks (audio processing, speech synthesis, conversation modelling, and data persistence).
- API Integration: The system design shows how external APIs (for NLP, TTS, etc.) are integrated into a cohesive service.
- Event-driven/Request-response flow: Incoming messages trigger a chain of module interactions and external API calls resulting in a tailored response.
- Lightweight data persistence: Using TinyDB simplifies storage without the overhead of a full-scale database solution.

##### Additional Details
- Remind your engineer that the main entry point is in main.py, coordinating the interactions between all these modular components.
- While the project isn’t built on an explicit MVC framework, the modular design in the src folder mimics a separation of logic similar to that pattern.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    subgraph "User Interaction"
        client["LINE Messaging Client"]:::client
    end

    %% Webhook/API Layer
    subgraph "Webhook/API Layer"
        controller["main.py (Webhook/API Controller)"]:::controller
    end

    %% Core Modules Layer
    subgraph "Core Modules"
        audio["audio.py (Audio Processing Module)"]:::module
        models["models.py (Conversation Models Module)"]:::module
        speech["speech.py (Text-to-Speech Module)"]:::module
        storage["storage.py (Data Persistence Module)"]:::module
    end

    %% External Services Layer
    subgraph "External Services"
        openai["OpenAI GPT-3.5 API"]:::external
        whisper["Whisper API"]:::external
        googletts["Google Text-To-Speech API"]:::external
        cronjob["CronJob Service"]:::external
    end

    %% Storage Backend
    subgraph "Storage Backend"
        tinydb["TinyDB Database"]:::database
    end

    %% Connections
    client -->|"sendsMessage"| controller
    controller -->|"invokesAudio"| audio
    controller -->|"invokesModels"| models
    controller -->|"invokesSpeech"| speech
    controller -->|"logsData"| storage
    storage -->|"persistsTo"| tinydb
    audio -->|"processesAudio"| whisper
    models -->|"callsGPT3.5"| openai
    models -->|"forwardsReply"| speech
    speech -->|"callsTTS"| googletts
    cronjob -->|"pings"| controller

    %% Click Events
    click controller "https://github.com/theexplainthis/chatgpt-ai-english-tutor/blob/main/main.py"
    click audio "https://github.com/theexplainthis/chatgpt-ai-english-tutor/blob/main/src/audio.py"
    click models "https://github.com/theexplainthis/chatgpt-ai-english-tutor/blob/main/src/models.py"
    click speech "https://github.com/theexplainthis/chatgpt-ai-english-tutor/blob/main/src/speech.py"
    click storage "https://github.com/theexplainthis/chatgpt-ai-english-tutor/blob/main/src/storage.py"
    click tinydb "https://github.com/theexplainthis/chatgpt-ai-english-tutor/tree/main/tinydb"

    %% Styles
    classDef client fill:#FFECB3,stroke:#333,stroke-width:2px
    classDef controller fill:#BBDEFB,stroke:#333,stroke-width:2px
    classDef module fill:#C8E6C9,stroke:#333,stroke-width:2px
    classDef external fill:#FFCDD2,stroke:#333,stroke-width:2px
    classDef database fill:#FFF9C4,stroke:#333,stroke-width:2px
```
