# zineb-kbyla/audio architecture

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

- Interactive diagram: https://gitdiagram.com/zineb-kbyla/audio
- Repository: https://github.com/zineb-kbyla/audio

## Overview

##### Project type and purpose
- This is a CLI-based Node.js/TypeScript utility whose job is to generate audio files for flashcards and quizzes (questions, responses, feedback), upload them to AWS S3, and update a PostgreSQL database with the resulting URLs. It also includes scripts to clear audio files and update story metadata. A Jest test suite covers each of these behaviors using Sinon and axios-mock-adapter.

##### File structure
- **Entry point**: `src/index.ts`
- **Command dispatch & argument parsing**: `src/util/parseArgv.ts`
- **Scripts folder (`src/scripts`)**: one script per feature:
- `flashcardsQuestions.ts`
- `flashcardsResponses.ts`
- `quizzesQuestions.ts`
- `quizzesFeedback.ts`
- `clearAudio.ts`
- `updateStories.ts`
- **Utilities (`src/util`)**:
- `db.ts` – manages PostgreSQL connection and CRUD operations
- `tts.ts` – wraps the ElevenLabs TTS API call
- `getTTSParams.ts` – builds language-specific TTS parameters using `src/enums`
- `s3.ts` – handles AWS S3 uploads and deletes
- `sleep.ts` – rate-limiting delay helper
- **Type definitions**: `src/interfaces` & `src/enums`
- **Configuration**: `.env`, `tsconfig.json`
- **Tests**: `_tests_/*.test.ts` verifying each integration and failure mode

##### README for architecture hints
- Emphasis on four major interactions:
1. TTS API (ElevenLabs)
2. AWS S3
3. PostgreSQL DB
4. Transaction rollbacks & error handling

##### Main components and relationships
a. **User CLI**
- User runs `yarn start --script <feature> --level <level>`.
- `src/index.ts` → `parseArgv` → selects correct script under `src/scripts`.
b. **Script**
- Reads questions or feedback from the database (via `db.ts`).
- For each text item:
- Build TTS parameters (`getTTSParams.ts`)
- Call ElevenLabs TTS API (`tts.ts`)
- Receive audio stream/buffer
- Upload to S3 (`s3.ts`), get back URL
- Update the database record with the S3 URL (`db.ts`), inside a transaction
- Special scripts like `clearAudio.ts` or `updateStories.ts` use S3 deletes or JSON file operations (`stories.json`).
c. **External services**
- **ElevenLabs API** (HTTP REST)
- **AWS S3** (SDK calls)
- **PostgreSQL** (SQL over TCP via a client library)

##### Important architectural patterns and design principles
- **Separation of concerns**:
- `src/index.ts` only dispatches commands
- Each script implements one feature
- Utilities encapsulate third-party integration
- **Modularity**: clear folder boundaries (scripts vs. util vs. interfaces)
- **Robust error handling**: each external call has retry or rollback logic
- **Testability**: utilities are easily mockable (axios-mock-adapter, Sinon)

##### Final checklist
- Clear component names matching file names (e.g., “FlashcardsQuestions Script”)
- Configuration sources (.env, stories.json) shown as input to the CLI or scripts

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration"
        env[".env"]:::config
        storiesFile["stories.json"]:::config
    end

    env --> CLI
    CLI["CLI Entrypoint\nindex.ts"]:::process
    click CLI "https://github.com/zineb-kbyla/audio/blob/master/src/index.ts"
    CLI --> parseArgv

    parseArgv["Argument Parser\nparseArgv.ts"]:::util
    click parseArgv "https://github.com/zineb-kbyla/audio/blob/master/src/util/parseArgv.ts"
    parseArgv --> Scripts

    subgraph "Scripts"
        FCQ["FlashcardsQuestions Script\nflashcardsQuestions.ts"]:::process
        click FCQ "https://github.com/zineb-kbyla/audio/blob/master/src/scripts/flashcardsQuestions.ts"
        FCR["FlashcardsResponses Script\nflashcardsResponses.ts"]:::process
        click FCR "https://github.com/zineb-kbyla/audio/blob/master/src/scripts/flashcardsResponses.ts"
        QQ["QuizzesQuestions Script\nquizzesQuestions.ts"]:::process
        click QQ "https://github.com/zineb-kbyla/audio/blob/master/src/scripts/quizzesQuestions.ts"
        QF["QuizzesFeedback Script\nquizzesFeeback.ts"]:::process
        click QF "https://github.com/zineb-kbyla/audio/blob/master/src/scripts/quizzesFeeback.ts"
        CA["ClearAudio Script\nclearAudio.ts"]:::process
        click CA "https://github.com/zineb-kbyla/audio/blob/master/src/scripts/clearAudio.ts"
        US["UpdateStories Script\nupdateStories.ts"]:::process
        click US "https://github.com/zineb-kbyla/audio/blob/master/src/scripts/updateStories.ts"
    end

    subgraph "Utilities"
        db["PostgreSQL Utility\ndb.ts"]:::util
        click db "https://github.com/zineb-kbyla/audio/blob/master/src/util/db.ts"
        params["TTS Params Builder\ngetTTSParams.ts"]:::util
        click params "https://github.com/zineb-kbyla/audio/blob/master/src/util/getTTSParams.ts"
        tts["TTS API Wrapper\ntts.ts"]:::util
        click tts "https://github.com/zineb-kbyla/audio/blob/master/src/util/tts.ts"
        s3["AWS S3 Utility\ns3.ts"]:::util
        click s3 "https://github.com/zineb-kbyla/audio/blob/master/src/util/s3.ts"
        sleep["Rate-Limit Sleep Helper\nsleep.ts"]:::util
        click sleep "https://github.com/zineb-kbyla/audio/blob/master/src/util/sleep.ts"
    end

    subgraph "Enums"
        scriptsEnum["ScriptsEnum.ts"]:::util
        click scriptsEnum "https://github.com/zineb-kbyla/audio/blob/master/src/enums/ScriptsEnum.ts"
        subjectEnum["SubjectEnum.ts"]:::util
        click subjectEnum "https://github.com/zineb-kbyla/audio/blob/master/src/enums/SubjectEnum.ts"
    end

    subgraph "Interfaces"
        flashInt["IFlashcardsQueryRes.ts"]:::util
        click flashInt "https://github.com/zineb-kbyla/audio/blob/master/src/interfaces/IFlashcardsQueryRes.ts"
        quizInt["IQuizzesQueryRes.ts"]:::util
        click quizInt "https://github.com/zineb-kbyla/audio/blob/master/src/interfaces/IQuizzesQueryRes.ts"
    end

    subgraph "External Systems"
        ElevenLabs["ElevenLabs TTS API"]:::external
        AWS["AWS S3"]:::external
        Postgres["PostgreSQL DB"]:::external
    end

    FCQ -->|"SQL SELECT"| db
    FCR -->|"SQL SELECT"| db
    QQ -->|"SQL SELECT"| db
    QF -->|"SQL SELECT"| db

    FCQ --> params --> tts -->|"TTS request"| ElevenLabs
    FCR --> params --> tts --> ElevenLabs
    QQ --> params --> tts --> ElevenLabs
    QF --> params --> tts --> ElevenLabs

    FCQ -->|"S3 PUT"| s3 -->|"Store audio"| AWS
    FCR -->|"S3 PUT"| s3 --> AWS
    QQ -->|"S3 PUT"| s3 --> AWS
    QF -->|"S3 PUT"| s3 --> AWS

    FCQ -->|"% SQL UPDATE"%| db
    FCR -->|"% SQL UPDATE"%| db
    QQ -->|"% SQL UPDATE"%| db
    QF -->|"% SQL UPDATE"%| db

    CA -->|"S3 DELETE"| s3 --> AWS
    US --> storiesFile

    FCQ --> sleep
    FCR --> sleep
    QQ --> sleep
    QF --> sleep

    US -.->|uses| db
    CA -.->|uses| db

    classDef process fill:#aaf,stroke:#000,stroke-width:1px;
    classDef util fill:#afa,stroke:#000,stroke-width:1px,stroke-dasharray:5 5;
    classDef external fill:#ffa,stroke:#000,stroke-width:1px;
    classDef config fill:#faa,stroke:#000,stroke-width:1px,stroke-dasharray:2 2;
```
