# ilialarchenko/interviewer architecture

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

- Interactive diagram: https://gitdiagram.com/ilialarchenko/interviewer
- Repository: https://github.com/ilialarchenko/interviewer

## Overview

##### Project type and purpose
- This is a full-stack, containerized AI interview simulator built with Python and Gradio.
- Purpose: provide a speech-first interface for mock technical interviews by orchestrating LLM calls, speech-to-text (STT), and text-to-speech (TTS).

##### File structure
- Top level
- app.py: entry point launching the Gradio UI and wiring together modules
- Dockerfile / docker-compose.yml: containerization and multi-service orchestration
- requirements.txt, .env examples: dependency and environment management
- Directories
- api/: modules encapsulating external AI calls (api/llm.py, api/audio.py)
- ui/: UI “controllers” splitting coding prompts and general instructions
- resources/: static prompts or data definitions used by the logic
- utils/: configuration loader, error definitions, parameter helpers, UI helpers
- tests/: end-to-end and unit tests verifying models, prompts, and flows

##### Extract architecture insights from the README
- The app orchestrates three AI model types: LLM, STT, TTS
- Environment configured via .env (keys, endpoints, model names)
- Supports OpenAI, Hugging Face, Anthropic, or local model endpoints
- Streaming data flows are supported for partial real-time responses

##### Main components
a. User client
- Web browser or Gradio embed
b. Gradio UI layer (app.py + ui/*)
- Input components: mic button (audio capture), text input
- Output components: text stream, audio playback
c. Controller/orchestration layer
- app.py routes user events to api and utils
- utils/config reads .env, selects model endpoints
- resources/prompts defines templated prompts
d. API adapters
- api/llm.py calls LLM endpoint (OpenAI, HF, Anthropic)
- api/audio.py handles STT and TTS calls (Whisper, tts-1, HF TTS)
e. External Model Services
- OpenAI (LLM, Whisper, TTS)
- Hugging Face inference endpoints or local model servers
f. Testing layer
- tests/* verifies each module independently (models, prompts, flow)
g. Infrastructure
- Docker container for the app
- docker-compose enabling multi-service (if local model servers are added)

##### Relationships and data flow
- User speaks or types → Gradio UI captures input → app.py
- For audio input: app.py → api/audio.py (STT) → transcribed text → back to app.py
- app.py assembles prompt with resources/prompts → api/llm.py → LLM response stream
- app.py passes LLM text to api/audio.py (TTS) → audio stream → Gradio UI
- All calls use utils/config settings for endpoints, keys, and model names

##### Architectural patterns and principles
- Layered architecture: UI layer, orchestration layer, adapter layer, external services
- Single-responsibility modules: ui/* only handles UI elements, api/* only calls external services, resources/* only holds static data
- Configuration-driven design via utils/config and .env examples
- Dependency injection via config for model URLs and types

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Host Browser"
        Browser["User Browser / Gradio UI"]:::frontend
    end

    subgraph "Docker Container"
        subgraph "UI Layer"
            AppUI["app.py"]:::frontend
            CodingUI["ui/coding.py"]:::frontend
            InstructionsUI["ui/instructions.py"]:::frontend
        end

        subgraph "Orchestration & Config"
            Controller["app.py"]:::core
            Config["utils/config.py"]:::config
            UIHelpers["utils/ui.py"]:::config
        end

        subgraph "API Adapters"
            LLM["api/llm.py"]:::adapter
            Audio["api/audio.py"]:::adapter
        end

        subgraph "Resources"
            Prompts["resources/prompts.py"]:::config
            DataRes["resources/data.py"]:::config
        end
    end

    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        HF["Hugging Face API"]:::external
        LocalModel["Local Model Server"]:::external
    end

    subgraph "Infrastructure & CI"
        DockerfileNode["Dockerfile"]:::infra
        Compose["docker-compose.yml"]:::infra
        Env1[".env.openai.example"]:::infra
        Env2[".env.huggingface.example"]:::infra
        Env3[".env.local.example"]:::infra
        Requirements["requirements.txt"]:::infra
        PytestIni["pytest.ini"]:::infra
        CI[".github/workflows/sync_to_huggingface.yml"]:::infra
    end

    subgraph "Testing Layer"
        TM["tests/test_models.py"]:::test
        TR["tests/test_resources.py"]:::test
        TS["tests/test_simulation.py"]:::test
        TT["tests/test_ttsmanager.py"]:::test
        TP["tests/testing_prompts.py"]:::test
        TA["tests/analysis.py"]:::test
        TC["tests/candidate.py"]:::test
        TG["tests/grader.py"]:::test
    end

    %% Data Flows
    Browser -->|"audio/text input"| AppUI
    AppUI -->|"invoke orchestrator"| Controller
    Controller -->|"reads config"| Config
    Controller -->|"uses UI helpers"| UIHelpers
    Controller -->|"assemble prompt"| Prompts
    Controller -->|"assemble data"| DataRes
    Controller -->|"call LLM"| LLM
    Controller -->|"call STT/TTS"| Audio

    LLM -->|"LLM endpoint"| OpenAI
    LLM -->|"LLM endpoint"| HF
    LLM -->|"LLM endpoint"| LocalModel
    OpenAI -->|"stream response"| LLM
    HF -->|"stream response"| LLM
    LocalModel -->|"stream response"| LLM

    Audio -->|"STT/TTS endpoint"| OpenAI
    Audio -->|"STT/TTS endpoint"| HF
    Audio -->|"STT/TTS endpoint"| LocalModel
    OpenAI -->|"audio stream"| Audio
    HF -->|"audio stream"| Audio
    LocalModel -->|"audio stream"| Audio

    Audio -->|"return text/audio"| Controller
    Controller -->|"send to UI"| AppUI
    AppUI -->|"render output"| Browser

    %% Testing Flows
    TM -.-> LLM
    TR -.-> Prompts
    TS -.-> Controller
    TT -.-> Audio
    TP -.-> Prompts
    TA -.-> DataRes
    TC -.-> Controller
    TG -.-> Controller

    %% Click Events
    click AppUI "https://github.com/ilialarchenko/interviewer/blob/main/app.py"
    click Controller "https://github.com/ilialarchenko/interviewer/blob/main/app.py"
    click CodingUI "https://github.com/ilialarchenko/interviewer/blob/main/ui/coding.py"
    click InstructionsUI "https://github.com/ilialarchenko/interviewer/blob/main/ui/instructions.py"
    click Config "https://github.com/ilialarchenko/interviewer/blob/main/utils/config.py"
    click UIHelpers "https://github.com/ilialarchenko/interviewer/blob/main/utils/ui.py"
    click LLM "https://github.com/ilialarchenko/interviewer/blob/main/api/llm.py"
    click Audio "https://github.com/ilialarchenko/interviewer/blob/main/api/audio.py"
    click Prompts "https://github.com/ilialarchenko/interviewer/blob/main/resources/prompts.py"
    click DataRes "https://github.com/ilialarchenko/interviewer/blob/main/resources/data.py"
    click DockerfileNode "https://github.com/ilialarchenko/interviewer/tree/main/Dockerfile"
    click Compose "https://github.com/ilialarchenko/interviewer/blob/main/docker-compose.yml"
    click Env1 "https://github.com/ilialarchenko/interviewer/blob/main/env_examples/.env.openai.example"
    click Env2 "https://github.com/ilialarchenko/interviewer/blob/main/env_examples/.env.huggingface.example"
    click Env3 "https://github.com/ilialarchenko/interviewer/blob/main/env_examples/.env.local.example"
    click Requirements "https://github.com/ilialarchenko/interviewer/blob/main/requirements.txt"
    click PytestIni "https://github.com/ilialarchenko/interviewer/blob/main/pytest.ini"
    click TM "https://github.com/ilialarchenko/interviewer/blob/main/tests/test_models.py"
    click TR "https://github.com/ilialarchenko/interviewer/blob/main/tests/test_resources.py"
    click TS "https://github.com/ilialarchenko/interviewer/blob/main/tests/test_simulation.py"
    click TT "https://github.com/ilialarchenko/interviewer/blob/main/tests/test_ttsmanager.py"
    click TP "https://github.com/ilialarchenko/interviewer/blob/main/tests/testing_prompts.py"
    click TA "https://github.com/ilialarchenko/interviewer/blob/main/tests/analysis.py"
    click TC "https://github.com/ilialarchenko/interviewer/blob/main/tests/candidate.py"
    click TG "https://github.com/ilialarchenko/interviewer/blob/main/tests/grader.py"

    %% Styles
    classDef frontend fill:#b2f7b2,stroke:#2d8f2d
    classDef core fill:#a2c9f5,stroke:#1f4f8b
    classDef adapter fill:#f5c68a,stroke:#b8741f
    classDef external fill:#d3d3d3,stroke:#999999
    classDef config fill:#fff3a2,stroke:#bfa31f
    classDef infra fill:#dcb2f7,stroke:#7a2d8f
    classDef test fill:#f7b2d2,stroke:#8f2d46
```
