# themodernturing/ai-learning-companion architecture

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

- Interactive diagram: https://gitdiagram.com/themodernturing/ai-learning-companion
- Repository: https://github.com/themodernturing/ai-learning-companion

## Overview

##### Project type and purpose
- It provides different modes (Student Mode, AI Learning Mode, About) and multiple grade-level chatbots (Grade 3–6).
- Utilities for AI interactions (ai_utils.py) and text-to-speech (tts_utils.py) indicate use of external AI and TTS services.

##### File structure
- Top-level:
- `.devcontainer/` for development environment config
- `app.py`: main entrypoint → launches the web server and routing
- `assets/`: static files (images, styles, etc.)
- `pages/`: individual page modules, each a Streamlit page component
- `utils/`: shared logic—`ai_utils.py`, `tts_utils.py`
- `requirements.txt`: lists Python dependencies
- `venv/`: Python virtual environment (not part of runtime arch)
- Pattern: Monolithic front-end + back-end in one process, with clear separation between UI pages and utility layers.

##### README
- No content provided; rely entirely on file structure.

##### Elements
– Clear labels: “User (Browser),” “Streamlit Server (app.py),” “Page: 1_Student_Mode,” etc.
- From User → Streamlit Server → Page Module → Utilities → External Service
- Back through the same chain to User

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User (Web Browser)"]:::user

    %% Server Layer
    Server["Streamlit Server<br/>app.py"]:::server

    %% UI Layer
    subgraph "UI Layer"
        Student["Student Mode Page"]:::ui
        AI_Learning["AI Learning Mode Page"]:::ui
        About["About Page"]:::ui
        Grade3["Grade 3 Chatbot Page"]:::ui
        Grade4["Grade 4 Chatbot Page"]:::ui
        Grade5["Grade 5 Chatbot Page"]:::ui
        Grade6["Grade 6 Chatbot Page"]:::ui
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        AIUtil["AI Utility Module"]:::logic
        TTSUtil["Text-to-Speech Utility Module"]:::logic
    end

    %% Assets Layer
    Assets["Static Assets"]:::assets

    %% External Services
    subgraph "External Services"
        AIService["External AI Service"]:::external
        TTSService["External TTS Service"]:::external
    end

    %% Development Environment
    Dev[".devcontainer/"]:::dev

    %% Connections
    User -->|"HTTP/WebSocket"| Server
    Server -->|"routes to"| Student
    Server -->|"routes to"| AI_Learning
    Server -->|"routes to"| About
    Server -->|"routes to"| Grade3
    Server -->|"routes to"| Grade4
    Server -->|"routes to"| Grade5
    Server -->|"routes to"| Grade6
    Server -->|"serves"| Assets

    Student -->|"calls"| AIUtil
    AI_Learning -->|"calls"| AIUtil
    Grade3 -->|"calls"| AIUtil
    Grade4 -->|"calls"| AIUtil
    Grade5 -->|"calls"| AIUtil
    Grade6 -->|"calls"| AIUtil

    Student -->|"calls"| TTSUtil
    AI_Learning -->|"calls"| TTSUtil
    Grade3 -->|"calls"| TTSUtil
    Grade4 -->|"calls"| TTSUtil
    Grade5 -->|"calls"| TTSUtil
    Grade6 -->|"calls"| TTSUtil

    AIUtil -->|"requests"| AIService
    TTSUtil -->|"requests"| TTSService

    %% Click Events
    click Server "https://github.com/themodernturing/ai-learning-companion/blob/main/app.py"
    click Student "https://github.com/themodernturing/ai-learning-companion/blob/main/pages/1_Student_Mode.py"
    click AI_Learning "https://github.com/themodernturing/ai-learning-companion/blob/main/pages/2_AI_Learning_Mode.py"
    click About "https://github.com/themodernturing/ai-learning-companion/blob/main/pages/3_About.py"
    click Grade3 "https://github.com/themodernturing/ai-learning-companion/blob/main/pages/Grade_3_chatbot.py"
    click Grade4 "https://github.com/themodernturing/ai-learning-companion/blob/main/pages/Grade_4_chatbot.py"
    click Grade5 "https://github.com/themodernturing/ai-learning-companion/blob/main/pages/Grade_5_chatbot.py"
    click Grade6 "https://github.com/themodernturing/ai-learning-companion/blob/main/pages/Grade_6_chatbot.py"
    click AIUtil "https://github.com/themodernturing/ai-learning-companion/blob/main/utils/ai_utils.py"
    click TTSUtil "https://github.com/themodernturing/ai-learning-companion/blob/main/utils/tts_utils.py"
    click Assets "https://github.com/themodernturing/ai-learning-companion/tree/main/assets/"
    click Dev "https://github.com/themodernturing/ai-learning-companion/tree/main/.devcontainer/"

    %% Styles
    classDef user fill:#f9f,stroke:#333,stroke-width:1px
    classDef server fill:#bbf,stroke:#333,stroke-width:1px
    classDef ui fill:#bfb,stroke:#333,stroke-width:1px
    classDef logic fill:#ffb,stroke:#333,stroke-width:1px
    classDef assets fill:#fcc,stroke:#333,stroke-width:1px
    classDef external fill:#fcf,stroke:#333,stroke-width:1px
    classDef dev fill:#eee,stroke:#333,stroke-width:1px
```
