# sanand0/generative-ai-group architecture

> Architecture diagram of the GitHub repository sanand0/generative-ai-group, 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/sanand0/generative-ai-group
- Repository: https://github.com/sanand0/generative-ai-group

## Overview

##### Project Type and Purpose
- This is an open-source, Python-based CLI tool (and library) that automates the transformation of a WhatsApp group JSON export into a weekly podcast.
- It performs a staged data-processing pipeline: reading/filtering messages → threading into weekly transcripts → generating a two-host dialogue script via OpenAI Chat API → producing per-speaker TTS audio → concatenating into an MP3 → releasing via GitHub.

##### Key Components
a. Inputs & Configuration
- gen-ai-messages.json – raw WhatsApp scrape JSON
- config.toml – voice/style and prompt overrides
- Environment: OPENAI_API_KEY, ffmpeg in PATH
b. CLI Entrypoint
- podcast.py invoked via `uv run podcast.py`
c. Core Pipeline Modules
1. load_messages()
2. group_by_week()
3. build_threads()
4. render_message() → writes weekly/messages.txt
5. get_podcast_script() → calls OpenAI Chat Completion (gpt-4.1-mini) → writes weekly/podcast.md
6. generate_podcast_audio()
- splits script by speaker
- calls OpenAI TTS (gpt-4o-mini-tts) → writes .opus files
- invokes ffmpeg to concatenate → weekly/podcast.mp3
d. Outputs
- {WEEK}/messages.txt, podcast.md, *.opus, podcast.mp3
- podcast.xml (RSS feed)
e. Release Automation
- GitHub Releases via `gh release` commands

##### External Services & Tools
- OpenAI Chat Completion API (script generation)
- OpenAI TTS API (audio synthesis)
- ffmpeg (audio concatenation)
- GitHub CLI (release management)

##### Relationships and Data Flows
- JSON Export → [load_messages] → filtered messages
→ [group_by_week] → per-week buckets
→ [build_threads] → threaded data
→ [render_message] → messages.txt
→ [get_podcast_script] → podcast.md (via Chat API)
→ [generate_podcast_audio]
––TTS API calls per speaker → .opus
––ffmpeg concat → podcast.mp3
→ [gh release] → remote GitHub release & podcast.xml

##### Architectural Patterns & Principles
- Linear pipeline: each stage reads from FS or in-memory object, writes artifacts for the next stage
- Modular functions: clear single responsibility for parsing, grouping, rendering, API interaction, and file I/O
- Configurable via TOML for easy extension and voice/prompt tuning

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        direction TB
        gen["gen-ai-messages.json"]:::artifact
        config["config.toml"]:::artifact
    end

    %% CLI Entrypoint
    podcastCLI["podcast.py"]:::internal

    %% Core Pipeline
    subgraph "Python Library"
        direction TB
        LM["load_messages()"]:::internal
        GBW["group_by_week()"]:::internal
        BT["build_threads()"]:::internal
        RM["render_message()"]:::internal
        GPS["get_podcast_script()"]:::internal
        GPA["generate_podcast_audio()"]:::internal
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ChatAPI["OpenAI Chat API\ngpt-4.1-mini"]:::external
        TTSAPI["OpenAI TTS API\ngpt-4o-mini-tts"]:::external
        FFMPEG["ffmpeg CLI"]:::external
        GHCLI["GitHub CLI"]:::external
    end

    %% File System Buckets
    subgraph "Weekly Buckets" 
        direction TB
        D1["2025-02-23/"]:::artifact
        D2["2025-03-02/"]:::artifact
        D3["2025-03-09/"]:::artifact
        D4["2025-03-16/"]:::artifact
        D5["2025-03-23/"]:::artifact
        D6["2025-03-30/"]:::artifact
        D7["2025-04-06/"]:::artifact
        D8["2025-04-13/"]:::artifact
        D9["2025-04-20/"]:::artifact
        D10["2025-04-27/"]:::artifact
        D11["2025-05-04/"]:::artifact
        D12["2025-05-11/"]:::artifact
        D13["2025-05-18/"]:::artifact
    end

    %% Artifacts
    subgraph "Artifacts"
        direction TB
        MSG["messages.txt"]:::artifact
        MD["podcast.md"]:::artifact
        OPUS["*.opus"]:::artifact
        MP3["podcast.mp3"]:::artifact
        XML["podcast.xml"]:::artifact
    end

    %% Documentation
    README["README.md"]:::artifact
    LICENSE["LICENSE"]:::artifact

    %% Data Flows
    gen -->|reads| LM
    config -->|loads| LM
    podcastCLI -->|invokes| LM

    LM -->|filtered messages| GBW
    GBW -->|weekly buckets| BT
    BT -->|threads| RM
    RM -->|writes| MSG
    MSG --> D1
    MSG --> D2
    MSG --> D3
    RM --> GPS
    GPS -->|writes| MD
    MD --> D1
    MD --> D2
    MD --> D3

    GPS -->|calls| ChatAPI
    GPS --> GPA
    GPA -->|split per speaker| TTSAPI
    GPA -->|concat| FFMPEG
    TTSAPI --> OPUS
    OPUS --> D1
    OPUS --> D2
    FFMPEG --> MP3
    MP3 --> D1
    MP3 --> D2

    MP3 -->|release| GHCLI
    GHCLI -->|publishes| XML

    README
    LICENSE

    %% Click Events
    click gen "https://github.com/sanand0/generative-ai-group/blob/main/./gen-ai-messages.json"
    click config "https://github.com/sanand0/generative-ai-group/blob/main/./config.toml"
    click podcastCLI "https://github.com/sanand0/generative-ai-group/blob/main/./podcast.py"
    click README "https://github.com/sanand0/generative-ai-group/blob/main/./README.md"
    click LICENSE "https://github.com/sanand0/generative-ai-group/tree/main/./LICENSE"
    click D1 "https://github.com/sanand0/generative-ai-group/tree/main/./2025-02-23/"
    click D2 "https://github.com/sanand0/generative-ai-group/tree/main/./2025-03-02/"
    click D3 "https://github.com/sanand0/generative-ai-group/tree/main/./2025-03-09/"
    click D4 "https://github.com/sanand0/generative-ai-group/tree/main/./2025-03-16/"
    click D5 "https://github.com/sanand0/generative-ai-group/tree/main/./2025-03-23/"
    click D6 "https://github.com/sanand0/generative-ai-group/tree/main/./2025-03-30/"
    click D7 "https://github.com/sanand0/generative-ai-group/tree/main/./2025-04-06/"
    click D8 "https://github.com/sanand0/generative-ai-group/tree/main/./2025-04-13/"
    click D9 "https://github.com/sanand0/generative-ai-group/tree/main/./2025-04-20/"
    click D10 "https://github.com/sanand0/generative-ai-group/tree/main/./2025-04-27/"
    click D11 "https://github.com/sanand0/generative-ai-group/tree/main/./2025-05-04/"
    click D12 "https://github.com/sanand0/generative-ai-group/tree/main/./2025-05-11/"
    click D13 "https://github.com/sanand0/generative-ai-group/tree/main/./2025-05-18/"
    click MD "https://github.com/sanand0/generative-ai-group/blob/main/./2025-02-23/podcast-2025-02-23.md"
    click OPUS "https://github.com/sanand0/generative-ai-group/tree/main/./2025-02-23/"
    classDef internal fill:#D6EAF8,stroke:#2980B9,color:#1B4F72
    classDef external fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef artifact fill:#FCF3CF,stroke:#F1C40F,color:#7D6608
```
