# nishuzumi/gemini-teacher architecture

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

- Interactive diagram: https://gitdiagram.com/nishuzumi/gemini-teacher
- Repository: https://github.com/nishuzumi/gemini-teacher

## Overview

##### Project type and purpose
- This is a Python-based command-line “English Speaking Assistant” that:
- Captures microphone audio
- Sends it to Google Gemini AI for speech recognition & evaluation
- Provides grammar/ pronunciation feedback
- Optionally uses ElevenLabs for text-to-speech output
- It’s neither a web app nor microservice cluster, but a single-process CLI tool that integrates with external AI services.

##### File structure
- Top-level files:
- `.env.example` / environment config
- `requirements.txt` / Python dependencies
- `starter.py` / the single entry-point and core logic
- No nested directories; all logic lives in or is imported by `starter.py`.
- External configuration (API keys) is managed via `.env`.

##### README for additional insights
- Describes real-time audio capture, AI-driven pronunciation assessment, grammar correction, scenario dialogues, and optional TTS.
- Lists dependencies: Python 3.11+, PortAudio/PyAudio, Gemini API, ElevenLabs API.
- Usage flow: record → send → receive feedback → display/improve.

##### Detail
- Modules, even if implemented in one file
- Environment config as a separate component feeding API clients
- Continuous feedback loop
- Do not forget optional paths like speech synthesis

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User\n(Microphone + Terminal UI)"]:::external

    %% Local Modules
    subgraph "Local Modules"
        direction TB
        AudioCapture["Audio Capture Module\n(PyAudio wrapper)"]:::local
        CoreController["Core Controller\n(starter.py)"]:::local
        ConfigLoader["Configuration Loader\n(dotenv)"]:::config
        GeminiClient["Google Gemini API Client"]:::local
        TTSClient["ElevenLabs TTS Client\n(optional)"]:::local
        OutputRenderer["Output Renderer\n(CLI feedback)"]:::local
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GoogleGemini["Google Gemini Service"]:::external
        ElevenLabsService["ElevenLabs Service"]:::external
    end

    %% Project Artifacts
    subgraph "Project Artifacts"
        direction TB
        EnvFile[".env.example"]:::config
        Requirements["requirements.txt"]:::doc
        Readme["README.md"]:::doc
    end

    %% Data Flow
    User -->|"speaks audio"| AudioCapture
    AudioCapture -->|"raw audio"| CoreController
    CoreController -->|"load keys"| ConfigLoader
    ConfigLoader -->|"API keys"| CoreController
    CoreController -->|"send audio"| GeminiClient
    GeminiClient -->|"REST call"| GoogleGemini
    GoogleGemini -->|"text +scores"| GeminiClient
    GeminiClient -->|"response"| CoreController
    CoreController -->|"send text"| TTSClient
    TTSClient -->|"REST call"| ElevenLabsService
    ElevenLabsService -->|"TTS audio"| TTSClient
    TTSClient -->|"audio"| CoreController
    CoreController -->|"display feedback"| OutputRenderer
    OutputRenderer -->|"feedback"| User

    %% Optional branch style
    CoreController -.->|optional if TTS key| TTSClient
    TTSClient -.->|optional| ElevenLabsService

    %% Click Events
    click CoreController "https://github.com/nishuzumi/gemini-teacher/blob/master/starter.py"
    click AudioCapture "https://github.com/nishuzumi/gemini-teacher/blob/master/starter.py"
    click ConfigLoader "https://github.com/nishuzumi/gemini-teacher/blob/master/starter.py"
    click GeminiClient "https://github.com/nishuzumi/gemini-teacher/blob/master/starter.py"
    click TTSClient "https://github.com/nishuzumi/gemini-teacher/blob/master/starter.py"
    click OutputRenderer "https://github.com/nishuzumi/gemini-teacher/blob/master/starter.py"
    click EnvFile "https://github.com/nishuzumi/gemini-teacher/blob/master/.env.example"
    click Requirements "https://github.com/nishuzumi/gemini-teacher/blob/master/requirements.txt"
    click Readme "https://github.com/nishuzumi/gemini-teacher/blob/master/README.md"

    %% Styles
    classDef local fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef doc fill:#90EE90,stroke:#333,stroke-width:1px
```
