# johnvic211/song-chords architecture

> Architecture diagram of the GitHub repository johnvic211/song-chords, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/johnvic211/song-chords
- Repository: https://github.com/johnvic211/song-chords

## Overview

##### Project type and purpose
- This is a single‑page application (SPA) built with React and Vite.
- It serves as a music/playlist viewer and manager, presenting song metadata and lyrics, with UI features like dark‑mode toggling, playlist creation, and key transposition.

##### File structure
- Top‑level artifacts:
- index.html & public/ → static HTML entry and public assets
- src/ → all React source code
- vite.config.js, package.json, eslint.config.js → build, dependency, and lint configuration
- Within src/:
- main.jsx & App.jsx → application entry point and root component
- src/assets/ → images or static assets (if any)
- src/data/ → static data modules (artist.jsx, songBank.jsx) and JSON (youth_service.json)
- src/components/ → reusable UI components, grouped by domain:
– app/ (Header, Footer, UseDarkMode)
– playlist/ (PlaylistManager, PlaylistSong, PlaylistSongManager)
– song/ (SongPage, SongLyrics, AutoScrollLyrics, MusicInformation, SongTransposer, TransposeKey, SettingsModal, Url, SongSelector)

##### README for additional insights
- Confirms the use of Vite’s fast‑refresh plugins for React
- Minimal setup, no backend—purely front‑end toolchain

a. Main components to include
- Browser / User Agent
- Dev Server (Vite) or Production Server (serving static files)
- React Application (JS bundle produced by Vite)
- Component Layers:
– App Shell (App.jsx → Header, Footer, UseDarkMode)
– Playlist Domain (PlaylistManager, PlaylistSong, PlaylistSongManager)
– Song Domain (SongPage, Lyrics, Transposer, SettingsModal, etc.)
- Data Layer (static modules in src/data and youth_service.json)
- Build & Tooling (Vite, Babel/SWC plugin, ESLint)
b. Relationships & interactions
- User → Browser → React App entry point
- React App ↔ Component hierarchy (parent→child)
- Components → Data modules (import) for song/artist info and JSON
- SongTransposer & TransposeKey → internal logic altering lyrics pitch
- UseDarkMode → toggles CSS class on document root
- Dev environment: Vite Dev Server ↔ Browser via HMR; Production: static host → Browser
c. Architectural patterns & design principles
- Component-based UI (React)
- Unidirectional data flow (props/state drilling from App → subcomponents)
- Separation of concerns (data modules vs. presentation components)
- Build‑time tooling (Vite & plugins) decoupled from runtime
d. Key technologies & libraries
- React (component rendering, hooks)
- Vite (bundling, dev server, HMR)
- ESLint (code quality)
- Babel or SWC via @vitejs/plugin‑react for fast refresh

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Entities
    User((User)):::external
    Browser((Browser)):::external

    User-->|interacts|Browser

    %% Dev & Production Servers
    subgraph "Dev & Prod Servers"
        DevServer(["Vite Dev Server"]):::external
        ProdServer(["Static Host"]):::external
    end

    Browser-->|"dev request"|DevServer
    DevServer<-->|"HMR loop"|Browser
    Browser-->|"prod request"|ProdServer

    %% Build & Tooling
    subgraph "Build & Tooling"
        ViteConfig["vite.config.js"]:::tool
        ESLintConfig["eslint.config.js"]:::tool
        PackageJSON["package.json"]:::tool
        Bundle(["Bundle (JS/CSS)"]):::tool
    end

    DevServer-->Bundle
    ProdServer-->Bundle
    ViteConfig-->Bundle
    ESLintConfig-->Bundle
    PackageJSON-->Bundle

    %% React Application
    subgraph "React Application"
        Entry["src/main.jsx"]:::frontend
        Root["src/App.jsx"]:::frontend
        Styles["src/index.css"]:::frontend

        Entry-->Root
        Root-->Styles
        Bundle-->Entry
    end

    %% App Shell
    subgraph "App Shell"
        Header["Header"]:::frontend
        Footer["Footer"]:::frontend
        DarkMode["UseDarkMode"]:::frontend

        Root-->Header
        Root-->Footer
        Root-->DarkMode
    end

    %% Playlist Domain
    subgraph "Playlist Domain"
        PM["PlaylistManager"]:::frontend
        PSong["PlaylistSong"]:::frontend
        PSM["PlaylistSongManager"]:::frontend

        Root-->PM
        PM-->PSong
        PM-->PSM
    end

    %% Song Domain
    subgraph "Song Domain"
        SongPage["SongPage"]:::frontend
        Lyrics["SongLyrics"]:::frontend
        AutoScroll["AutoScrollLyrics"]:::frontend
        Info["MusicInformation"]:::frontend
        Transposer["SongTransposer"]:::frontend
        Key["TransposeKey"]:::frontend
        Modal["SettingsModal"]:::frontend
        URL["Url"]:::frontend
        Selector["SongSelector"]:::frontend

        Root-->SongPage
        SongPage-->Lyrics
        SongPage-->AutoScroll
        SongPage-->Info
        SongPage-->Transposer
        Transposer-->Key
        SongPage-->Modal
        SongPage-->URL
        Root-->Selector
    end

    %% Data Layer
    subgraph "Data Layer"
        Artist(["artist.jsx"]):::data
        SongBank(["songBank.jsx"]):::data
        YouthService(("youth_service.json")):::data

        PM-->Artist
        PSong-->SongBank
        SongPage-->SongBank
        SongPage-->Artist
        Lyrics-->YouthService
    end

    %% Click Events
    click ViteConfig "https://github.com/johnvic211/song-chords/blob/main/vite.config.js"
    click ESLintConfig "https://github.com/johnvic211/song-chords/blob/main/eslint.config.js"
    click PackageJSON "https://github.com/johnvic211/song-chords/blob/main/package.json"
    click Entry "https://github.com/johnvic211/song-chords/blob/main/src/main.jsx"
    click Root "https://github.com/johnvic211/song-chords/blob/main/src/App.jsx"
    click Styles "https://github.com/johnvic211/song-chords/blob/main/src/index.css"
    click Header "https://github.com/johnvic211/song-chords/blob/main/src/components/app/Header.jsx"
    click Footer "https://github.com/johnvic211/song-chords/blob/main/src/components/app/Footer.jsx"
    click DarkMode "https://github.com/johnvic211/song-chords/blob/main/src/components/app/UseDarkMode.jsx"
    click PM "https://github.com/johnvic211/song-chords/blob/main/src/components/playlist/PlaylistManager.jsx"
    click PSong "https://github.com/johnvic211/song-chords/blob/main/src/components/playlist/PlaylistSong.jsx"
    click PSM "https://github.com/johnvic211/song-chords/blob/main/src/components/playlist/PlaylistSongManager.jsx"
    click SongPage "https://github.com/johnvic211/song-chords/blob/main/src/components/song/SongPage.jsx"
    click Lyrics "https://github.com/johnvic211/song-chords/blob/main/src/components/song/SongLyrics.jsx"
    click AutoScroll "https://github.com/johnvic211/song-chords/blob/main/src/components/song/AutoScrollLyrics.jsx"
    click Info "https://github.com/johnvic211/song-chords/blob/main/src/components/song/MusicInformation.jsx"
    click Transposer "https://github.com/johnvic211/song-chords/blob/main/src/components/song/SongTransposer.jsx"
    click Key "https://github.com/johnvic211/song-chords/blob/main/src/components/song/TransposeKey.jsx"
    click Modal "https://github.com/johnvic211/song-chords/blob/main/src/components/song/SettingsModal.jsx"
    click URL "https://github.com/johnvic211/song-chords/blob/main/src/components/song/Url.jsx"
    click Selector "https://github.com/johnvic211/song-chords/blob/main/src/components/song/SongSelector.jsx"
    click Artist "https://github.com/johnvic211/song-chords/blob/main/src/data/artist.jsx"
    click SongBank "https://github.com/johnvic211/song-chords/blob/main/src/data/songBank.jsx"
    click YouthService "https://github.com/johnvic211/song-chords/blob/main/src/data/youth_service.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef data fill:#E0F7E9,stroke:#1E8E3E,stroke-width:1px
    classDef tool fill:#F0F0F0,stroke:#777777,stroke-width:1px
    classDef external fill:#FFF3CD,stroke:#D39E00,stroke-width:1px
```
