# ldenoue/readabletranscripts architecture

> Architecture diagram of the GitHub repository ldenoue/readabletranscripts, 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/ldenoue/readabletranscripts
- Repository: https://github.com/ldenoue/readabletranscripts

## Overview

##### Main Components
- • Web UI Component:
- Represents the static HTML (index.html) and CSS (styles.css) files that form the presentation layer.
- Displays the video transcript, interactive elements, and the demo interface.
- • JavaScript Application Logic:
- code.js: This is the core script that handles fetching the YouTube transcript, sending video metadata and transcript chunks to the Gemini API, handling responses, and orchestrating the progressive transformation of the transcript.
- diff2.js: This script manages the alignment between the raw YouTube transcript and the processed transcript (implementing a diff algorithm) for proper word highlighting.
- localforage-getitems.js: A utility for managing client-side storage (likely caching API keys, transcripts, or other user-specific data).
- • External APIs and Services:
- Gemini Flash 8B API: The service used to process vocabulary extraction, formatting of transcript chunks, and merging at the boundaries.
- YouTube Transcript Source: The origin for raw transcript data (even though the fetching mechanism is implemented in the client-side JavaScript, it’s a crucial external dependency).

##### Relationships and Interactions
- The User loads index.html in a modern browser.
- The browser renders the UI using styles.css.
- The UI is powered by code.js, which controls the application flow:
a. On load or on user interaction, code.js fetches the raw YouTube transcript (or uses sample JSON files available in the examples folder).
b. It extracts vocabulary words from the video title and description by sending a request to the Gemini API for context and formatting.
c. The transcript is chunked (512 words per chunk) and concurrently sent to the Gemini API for processing.
d. After receiving the responses, code.js coordinates with diff2.js to merge adjacent chunks (especially merging the boundary sentences) and then align the raw timestamps with the newly formatted text via a diffing algorithm.
e. localforage-getitems.js is used where necessary to cache or retrieve locally stored data (like the Gemini API key or processed transcript pieces).
- From code.js → Gemini Flash 8B API (for formatting requests).
- Gemini API responses → code.js (processing and merging).
- The final merged transcript along with timestamp alignment is then used to perform interactive UI functions (e.g., clicking words to jump to video timestamps).

##### Architectural Patterns and Design Principles
- Modular Frontend Design: The separation of concerns is clear—HTML/CSS handles presentation while JavaScript modules (code.js, diff2.js, storage utilities) manage application logic.
- Asynchronous Parallel Processing: The system sends transcript formatting requests in parallel to the Gemini API, indicating a design optimized for responsiveness.
- Data Transformation Pipeline: The transcript undergoes multiple stages—extracting vocabulary context, chunking, formatting via API calls, merging chunks, and diff alignment—before being presented.

##### Relevant Technologies and Libraries
- Vanilla JavaScript (or light-weight frameworks/libraries if used, though not explicitly stated).
- A simple HTTP server for local development (e.g., using Python’s http.server module).
- External Gemini Flash 8B API for language processing.
- HTML5 and CSS for the front-end user interface.
- LocalForage (implied by localforage-getitems.js) for client-side storage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User Browser"]:::user
    UI["Web UI (index.html & styles.css)"]:::ui
    Logic["Application Logic (code.js)"]:::logic
    Diff["Transcript Diffing Module (diff2.js)"]:::logic
    Storage["Local Storage Utility (localforage-getitems.js)"]:::logic

    subgraph "External Services"
        YT["YouTube Transcript Source (Data Provider, includes examples folder)"]:::external
        Gemini["Gemini Flash 8B API (External Service)"]:::external
    end

    User -->|"loads"| UI
    UI -->|"initiates"| Logic
    Logic -->|"fetchTranscript"| YT
    Logic -->|"sendChunks"| Gemini
    Gemini -->|"formattedChunks"| Logic
    Logic -->|"diffAlignment"| Diff
    Logic -->|"cacheRetrieve"| Storage
    Logic -->|"displayTranscript"| UI

    click UI "https://github.com/ldenoue/readabletranscripts/blob/main/index.html"
    click Logic "https://github.com/ldenoue/readabletranscripts/blob/main/code.js"
    click Diff "https://github.com/ldenoue/readabletranscripts/blob/main/diff2.js"
    click Storage "https://github.com/ldenoue/readabletranscripts/blob/main/localforage-getitems.js"
    click YT "https://github.com/ldenoue/readabletranscripts/tree/main/examples"

    classDef user fill:#AED6F1,stroke:#1F618D,color:#1F618D;
    classDef ui fill:#ABEBC6,stroke:#27AE60,color:#1E8449;
    classDef logic fill:#F9E79F,stroke:#B7950B,color:#7D6608;
    classDef external fill:#F5B7B1,stroke:#C0392B,color:#641E16;
```
