# sairam4123/iras-new architecture

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

- Interactive diagram: https://gitdiagram.com/sairam4123/iras-new
- Repository: https://github.com/sairam4123/iras-new

## Overview

##### Main Components
- Data Acquisition & Parsing:
- etrainlib is responsible for scraping train data from etrain.info. It contains modules like _async.py, _sync.py, constants.py, and parser.py.
- clean_data.py further processes raw data, while stations.json may serve as a static data reference.
- Announcement Management:
- The core logic involves priority queue management (found in player.py, console.py, and main.py) that decides the order of announcements.
- There is a processing pipeline that takes the clean, parsed train data and schedules announcements based on priority (e.g., "Train is arriving" vs. "Scheduled departure").
- Audio Generation:
- espeak_ng wraps the text-to-speech engine functionality to generate audio from announcement text.
- External assets in the "announcers/sounds" directory (various WAV files) are integrated to add signature chimes or notification sounds.
- GTTS is mentioned in the README as the engine for converting text to audio in multiple languages.
- Audio Playback & Interface:
- Two distinct entry points: console.py for the standalone application and main.py for the Discord Bot implementation.
- The Discord implementation includes integration with the Discord API (and requires a bot token) and the console mode interacts directly with the system's audio output.
- External Dependencies:
- FFMpeg is used to process or play audio files.
- eSpeak-NG (as a system executable) must be in the system path.
- Discord-related credentials are needed if opting for the Discord deployment.

##### Relationships and Interactions
- Data Flow: etrainlib fetches and parses live train data → clean_data.py refines the data → the announcement manager (integrated into player.py, console.py, and main.py) organizes messages according to their priority.
- Audio Flow: Once an announcement is prioritized, the system uses GTTS and/or espeak_ng to generate audio, optionally appending the signature chime from "announcers/sounds" → the resulting file is queued for playback.
- Deployment Mode: The architecture bifurcates into two operational modes:
◦ Discord Bot: main.py sets up the connections to Discord, processes announcements, and plays them on a Discord server.
◦ Console App: console.py handles local playback, managing audio output through the system speakers.

##### Architectural Patterns & Design Principles
- Modularity: Distinct libraries (etrainlib and espeak_ng) encapsulate key functionalities that can be modified or replaced independently.
- Separation of Concerns: The system design clearly separates data acquisition, announcement handling, audio generation, and playback into different modules.
- Priority Queue Management: The announcement scheduling system uses a priority-based approach to ensure that high-priority announcements are played before lower-priority ones.
- Dual Deployment Paths: There’s a clear separation between Discord-based and locally run (console) applications ensuring flexibility.

##### Implementation Notes for the Principal Software Engineer
- Keep labels clear and use descriptive names (e.g., "Train Data Scraper (etrainlib)", "Priority Announcement Manager", "Text-to-Speech Engine (espeak_ng & GTTS)").
- If possible, include sub-components (like differentiating async vs. sync operations in etrainlib) especially if they have a significant role in overall system performance.
- Dual operational modes by clearly distinguishing which components are shared and which are unique to the Discord Bot or Console App.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Acquisition & Processing
    subgraph "Data Acquisition & Processing"
        A["Train Data Scraper (etrainlib)"]:::internal
        B["Data Cleaning (clean_data.py)"]:::internal
        C["Stations Reference (stations.json)"]:::data
    end
    A -->|"scrapes data"| B
    B -->|"refines data"| C

    %% Announcement Management (Priority Queue)
    subgraph "Announcement Management"
        D["Priority Announcement Manager (player.py)"]:::internal
    end
    C -->|"sends cleaned data"| D

    %% Audio Generation Module
    subgraph "Audio Generation"
        E["Text-to-Speech Engine (espeak_ng & GTTS)"]:::audio
        F["Sound Assets (announcers/sounds)"]:::asset
    end
    D -->|"schedules announcement"| E
    E -.->|"adds chime"| F
    E -->|"processes audio"| X["FFMpeg (External)"]:::external
    E -->|"invokes"| Y["eSpeak-NG Exec (External)"]:::external

    %% Playback Interfaces
    subgraph "Playback Interfaces"
        G["Discord Bot Interface (main.py)"]:::interface
        H["Console App Interface (console.py)"]:::interface
    end
    E -->|"outputs to"| G
    E -->|"outputs to"| H
    G -->|"connects to"| Z["Discord API (External)"]:::external

    %% External Data Source
    W["etrain.info (External)"]:::external
    A -->|"fetches live data from"| W

    %% Click Events
    click A "https://github.com/sairam4123/iras-new/tree/main/etrainlib/"
    click B "https://github.com/sairam4123/iras-new/blob/main/clean_data.py"
    click C "https://github.com/sairam4123/iras-new/blob/main/stations.json"
    click D "https://github.com/sairam4123/iras-new/blob/main/player.py"
    click G "https://github.com/sairam4123/iras-new/blob/main/main.py"
    click H "https://github.com/sairam4123/iras-new/blob/main/console.py"
    click E "https://github.com/sairam4123/iras-new/tree/main/espeak_ng/"
    click F "https://github.com/sairam4123/iras-new/tree/main/announcers/sounds/"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef data fill:#e2e3e5,stroke:#383d41,stroke-width:2px;
    classDef audio fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef asset fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef interface fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#fefefe,stroke:#6c757d,stroke-dasharray: 5 5,stroke-width:2px;
```
