# developerrahulofficial/lyrics-elements architecture

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

- Interactive diagram: https://gitdiagram.com/developerrahulofficial/lyrics-elements
- Repository: https://github.com/developerrahulofficial/lyrics-elements

## Overview

##### Project type and purpose
- This is a single-page React+TypeScript front-end application (built with Vite) that runs entirely in the browser.
- Purpose: take user-uploaded MP3 and timed lyrics, map each word to periodic-table elements (or emoji/physics symbols), render an animated lyric video in sync with the audio, and export it via FFmpeg compiled to WebAssembly.

##### File structure
- Top-level:
- package.json, tsconfig*, vite.config.ts → build & config
- public/ → static assets (demo.mp3, robots.txt, index.html, ffmpeg WASM module)
- src/ → source code
- src/ breakdown:
- components/ → React UI components (AddMp3Button, FileUpload, VideoEditor, LyricsEditor, LyricsDisplay, ExportVideo, AudioPlayer, ThemeSwitcher, etc.)
- components/ui/ → library of reusable design system primitives (buttons, dialogs, sliders…)
- hooks/ → cross-cutting logic (use-mobile, use-toast)
- lib/utils.ts → generic helpers
- utils/ → domain logic (lyricsService.ts, periodicTable.ts, videoExporter.ts)
- pages/ → route entry points (Index, NotFound)
- main.tsx, App.tsx → application root
- public/ffmpeg → ffmpeg-core.js/.wasm/.worker.js for client-side video encoding

##### Key insights from README
- Core algorithm flow:
1. parse lyrics & timestamps
2. lookup in emojiMap.ts → periodicTable.ts → physicsMap
3. render stacked blocks via React + Framer Motion
4. hand off rendered frames + audio to FFmpeg WASM for export
- Tech stack: React, TypeScript, TailwindCSS, Vite, Framer Motion, FFmpeg WASM.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External actor
    U["User"]:::external

    subgraph "Browser (Client)"
        subgraph "React Application"
            subgraph "UI Layer"
                A1["AddMp3Button\nsrc/components/AddMp3Button.tsx"]:::ui
                A2["FileUpload\nsrc/components/FileUpload.tsx"]:::ui
                A3["AudioPlayer\nsrc/components/AudioPlayer.tsx"]:::ui
                A4["LyricsEditor\nsrc/components/LyricsEditor.tsx"]:::ui
                A5["LyricsDisplay\nsrc/components/LyricsDisplay.tsx"]:::ui
                A6["VideoEditor\nsrc/components/VideoEditor.tsx"]:::ui
                A7["ExportVideo\nsrc/components/ExportVideo.tsx"]:::ui
                A8["ThemeSwitcher\nsrc/components/ThemeSwitcher.tsx"]:::ui
                A9["ElementTile\nsrc/components/ElementTile.tsx"]:::ui
                A10["LyricsSearch\nsrc/components/LyricsSearch.tsx"]:::ui
            end
            subgraph "Domain Logic"
                D1["lyricsService\nsrc/utils/lyricsService.ts"]:::domain
                D2["periodicTable\nsrc/utils/periodicTable.ts"]:::domain
                D5["emojiMap\nsrc/utils/emojiMap.ts"]:::domain
                D6["physicsMap\nsrc/utils/physicsMap.ts"]:::domain
                D3["videoExporter\nsrc/utils/videoExporter.ts"]:::domain
            end
            D4["utils\nsrc/lib/utils.ts"]:::domain
        end

        subgraph "Framer Motion Renderer"
            R["Canvas/WebGL\nframe capture"]:::browserapi
        end

        subgraph "FFmpeg WASM Module"
            W1["ffmpeg-core.js\npublic/ffmpeg/ffmpeg-core.js"]:::wasm
            W2["ffmpeg-core.wasm\npublic/ffmpeg/ffmpeg-core.wasm"]:::wasm
            W3["ffmpeg-core.worker.js\npublic/ffmpeg/ffmpeg-core.worker.js"]:::wasm
        end

        BrowserAPIAudio["Audio API"]:::browserapi
        BrowserAPICanvas["Canvas/WebGL API"]:::browserapi

        subgraph "Assets & Static Files"
            S1["demo.mp3\npublic/demo.mp3"]:::static
            S2["index.html\npublic/index.html"]:::static
            S3["ffmpeg-core.js/.wasm/.worker\npublic/ffmpeg"]:::static
        end
    end

    %% Data flows
    U -->|".mp3 file"| A2
    A2 -->|".mp3"| BrowserAPIAudio
    U -->|"timestamped lyrics JSON"| A4
    A4 -->|"lyrics & timestamps"| D1
    D1 -->|"lookup"| D2
    D1 -->|"lookup"| D5
    D1 -->|"lookup"| D6
    D1 -->|"mapped sequence"| A5
    D1 -->|"mapped sequence"| A6
    A7 -->|"export trigger"| D3
    D3 -->|"frame bitmaps"| BrowserAPICanvas
    BrowserAPICanvas -->|"encode"| W1
    W1 -->|"video blob"| U

    %% Click events
    click A1 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/src/components/AddMp3Button.tsx"
    click A2 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/src/components/FileUpload.tsx"
    click A3 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/src/components/AudioPlayer.tsx"
    click A4 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/src/components/LyricsEditor.tsx"
    click A5 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/src/components/LyricsDisplay.tsx"
    click A6 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/src/components/VideoEditor.tsx"
    click A7 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/src/components/ExportVideo.tsx"
    click A8 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/src/components/ThemeSwitcher.tsx"
    click A9 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/src/components/ElementTile.tsx"
    click A10 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/src/components/LyricsSearch.tsx"
    click D1 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/src/utils/lyricsService.ts"
    click D2 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/src/utils/periodicTable.ts"
    click D3 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/src/utils/videoExporter.ts"
    click D4 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/src/lib/utils.ts"
    click W1 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/public/ffmpeg/ffmpeg-core.js"
    click W2 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/public/ffmpeg/ffmpeg-core.wasm"
    click W3 "https://github.com/developerrahulofficial/lyrics-elements/blob/main/public/ffmpeg/ffmpeg-core.worker.js"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0066CC,color:#000;
    classDef domain fill:#DFF2D8,stroke:#339900,color:#000;
    classDef wasm fill:#E8D0FF,stroke:#9900CC,color:#000;
    classDef browserapi fill:#FFE8D0,stroke:#CC6600,color:#000;
    classDef static fill:#F0F0F0,stroke:#999999,color:#000;
    classDef external fill:#FFFFFF,stroke:#000000,stroke-dasharray: 5 5;color:#000;
```
