# shravasti221/birminghack architecture

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

- Interactive diagram: https://gitdiagram.com/shravasti221/birminghack
- Repository: https://github.com/shravasti221/birminghack

## Overview

##### Project type and purpose
- StoryPhonic is a full-stack web application (built with Python/Flask) that converts user-supplied text into a narrated audio experience using AI-driven text parsing, voice assignment, and speech synthesis. The README confirms features such as dynamic dialogue extraction, celebrity voice casting, and exportable audio.

##### File structure
Top-level components:
- app.py & routes.py – Flask application and HTTP route definitions
- config.py – configuration for API keys, voice model endpoints, etc.
- utils.py, load_text.py, voice_assigner.py, merge_audio_files.py, get_voices.py – core processing modules
- generator_async_SSE.py – Server-Sent Events stream for real-time audio generation
- audio_samples/ & voices.csv / chars_gender.txt – static data stores for sample audio, voice metadata, and parsing dictionaries
- templates/index.html + static/style.css – front-end presentation layer
- requirements.txt – Python dependencies

##### README for architectural hints
- The app ingests raw text (user upload or paste).
- It extracts characters and dialogues, then assigns user-chosen celebrity voices.
- It invokes an external AI speech synthesis API for each turn of dialogue or narration.
- It merges the resulting audio clips into a final output (a downloadable audio file).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Client
    subgraph "Frontend Client"
        direction TB
        BrowserUI["Browser UI<br/>(templates/index.html, static/style.css)"]:::frontend
    end

    %% Flask Backend
    subgraph "Flask Backend"
        direction TB
        App["Flask App<br/>(app.py)"]:::backend
        Routes["HTTP Routes<br/>(routes.py)"]:::backend
        SSE["SSE Controller<br/>(generator_async_SSE.py)"]:::backend
        LoadText["Text Ingestion<br/>(load_text.py)"]:::process
        Utils["Dialogue Extraction<br/>(utils.py)"]:::process
        Assign["Voice Assignment<br/>(voice_assigner.py)"]:::process
        GetVoices["TTS Integration<br/>(get_voices.py)"]:::process
        Merge["Audio Merging<br/>(merge_audio_files.py)"]:::process
    end

    %% Configuration & Dependencies
    subgraph "Config & Dependencies"
        direction TB
        Config["Configuration<br/>(config.py)"]:::config
        Req["Python Dependencies<br/>(requirements.txt)"]:::config
    end

    %% Storage
    subgraph "File Storage"
        direction TB
        Parsed["Parsed Text<br/>(parsed_text.txt)"]:::storage
        AudioSamples["Audio Samples<br/>(audio_samples/)"]:::storage
    end

    %% External TTS Service
    ExternalAPI[(External AI Speech API)]:::external

    %% Flows
    BrowserUI -->|HTTP POST /generate| App
    App --> Routes
    Routes --> LoadText
    LoadText --> Utils
    Utils --> Assign
    Assign --> Parsed
    Assign -->|reads metadata| Utils
    Config --> Assign
    Config --> GetVoices
    Config --> Merge

    Assign --> SSE
    SSE -->|SSE stream| GetVoices
    GetVoices -->|HTTP API call| ExternalAPI
    ExternalAPI -->|Audio Bytes| AudioSamples
    AudioSamples --> Merge
    Merge -->|Final Audio| SSE
    SSE -->|SSE events| BrowserUI

    %% Click Events
    click BrowserUI "https://github.com/shravasti221/birminghack/blob/master/templates/index.html"
    click BrowserUI "https://github.com/shravasti221/birminghack/blob/master/static/style.css"
    click App "https://github.com/shravasti221/birminghack/blob/master/app.py"
    click Routes "https://github.com/shravasti221/birminghack/blob/master/routes.py"
    click SSE "https://github.com/shravasti221/birminghack/blob/master/generator_async_SSE.py"
    click LoadText "https://github.com/shravasti221/birminghack/blob/master/load_text.py"
    click Parsed "https://github.com/shravasti221/birminghack/blob/master/parsed_text.txt"
    click Utils "https://github.com/shravasti221/birminghack/blob/master/utils.py"
    click Assign "https://github.com/shravasti221/birminghack/blob/master/voice_assigner.py"
    click Assign "https://github.com/shravasti221/birminghack/blob/master/chars_gender.txt"
    click Assign "https://github.com/shravasti221/birminghack/blob/master/voices.csv"
    click GetVoices "https://github.com/shravasti221/birminghack/blob/master/get_voices.py"
    click Merge "https://github.com/shravasti221/birminghack/blob/master/merge_audio_files.py"
    click AudioSamples "https://github.com/shravasti221/birminghack/tree/master/audio_samples/"
    click Config "https://github.com/shravasti221/birminghack/blob/master/config.py"
    click Req "https://github.com/shravasti221/birminghack/blob/master/requirements.txt"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#1B4F72;
    classDef backend fill:#D5F5E3,stroke:#196F3D,color:#196F3D;
    classDef process fill:#FCF3CF,stroke:#B7950B,color:#B7950B;
    classDef storage fill:#FADBD8,stroke:#CB4335,color:#CB4335;
    classDef external fill:#EBDEF0,stroke:#6C3483,color:#6C3483;
    classDef config fill:#F2F3F4,stroke:#515A5A,color:#515A5A;
```
