# jadddxx/sing-a-song architecture

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

- Interactive diagram: https://gitdiagram.com/jadddxx/sing-a-song
- Repository: https://github.com/jadddxx/sing-a-song

## Overview

##### Project type and purpose
- This is a single-page, client-side web application (“sing-a-song”) originally built as part of the JS30 challenge.
- Purpose: listen for voice input of a song title, match it against a small library of MP3 files, and play the corresponding track if the user’s pronunciation is correct.

##### File structure
Top-level:
- index.html – the entry point and root of the UI
- js/main.js – contains the speech-recognition logic and audio playback code
- scss/… & style/style.css – styling, organized into layout and component partials, compiled to CSS
- song/… – static MP3 assets to be served
- node_modules, package.json/lock – build toolchain for SCSS compilation (and optional local dev server)
No backend folder: it’s a purely front-end, static site intended for GitHub Pages (or any static hosting).

##### README
- Confirms usage: user “says” a song name, and if recognized correctly via the Web Speech API, the MP3 from song/ is played.
- Deployed at jadddxx.github.io/sing-a-song (static hosting).

a. Main components:
1. User’s Browser (client)
2. UI Layer (HTML + CSS)
3. Speech Recognition Engine (Web Speech API in the browser)
4. Application Logic (js/main.js)
5. Audio Playback Module (HTML5 Audio API)
6. Static Assets Server (hosts index.html, CSS, JS, MP3 files)
b. Relationships & interactions:
- User speaks into the mic → Browser’s Speech Recognition
- Recognized text forwarded to Application Logic
- Logic compares text against available song titles (from a local lookup or in-code list)
- On match → Audio Playback Module requests and plays the corresponding MP3 from the static assets server
- UI Layer updates (e.g., highlights success/ failure, displays recognized transcript)
c. Architectural patterns/design principles:
- Single-page application (SPA) pattern: static HTML + JS handles all interactions
- Separation of concerns:
- View: SCSS/CSS + HTML (layout vs. component partials)
- Controller/Logic: main.js handles events and business logic
- Assets layer: song directory acts as static resource pool
- Progressive enhancement: uses built-in browser APIs (no heavy frameworks)
d. Key technologies/frameworks/libraries:
- Web Speech API (SpeechRecognition)
- HTML5 Audio API
- SCSS → CSS build tool (node-sass or dart-sass via npm scripts)
- Static hosting (GitHub Pages or any CDN)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::external

    %% Static Assets Server
    SERVER["Static Assets Server"]:::server

    %% UI / Assets Subgraph
    subgraph "UI / Assets"
        HTML["index.html"]:::uiAssets
        CSS["style/style.css"]:::uiAssets
        SONG["Song Library (MP3s)"]:::uiAssets
    end

    %% Build Toolchain Subgraph
    subgraph "Build Toolchain"
        SCSS["scss/"]:::build
        NPM1["package.json"]:::build
        NPM2["package-lock.json"]:::build
        NODEMOD["node_modules/"]:::build
    end

    %% Browser APIs Subgraph
    subgraph "Browser APIs"
        SPEECH["SpeechRecognition API"]:::browserAPI
        AUDIOAPI["HTML5 Audio API"]:::browserAPI
    end

    %% Application Logic
    LOGIC["Application Logic (js/main.js)"]:::logic

    %% Flows
    User -->|visits| SERVER
    SERVER -->|delivers| HTML
    SERVER -->|delivers| CSS
    SERVER -->|delivers| LOGIC

    SCSS -->|compiles via npm script| CSS

    User -->|speaks into mic| SPEECH
    SPEECH -->|transcript| LOGIC
    LOGIC -->|loads audio| AUDIOAPI
    LOGIC -->|requests MP3| SERVER
    SERVER -->|serves file| SONG
    SONG -->|audio data| AUDIOAPI
    AUDIOAPI -->|plays sound| User

    %% Click Events
    click HTML "https://github.com/jadddxx/sing-a-song/blob/master/index.html"
    click CSS "https://github.com/jadddxx/sing-a-song/blob/master/style/style.css"
    click SCSS "https://github.com/jadddxx/sing-a-song/tree/master/scss/"
    click LOGIC "https://github.com/jadddxx/sing-a-song/blob/master/js/main.js"
    click SONG "https://github.com/jadddxx/sing-a-song/tree/master/song/"
    click NPM1 "https://github.com/jadddxx/sing-a-song/blob/master/package.json"
    click NPM2 "https://github.com/jadddxx/sing-a-song/blob/master/package-lock.json"
    click NODEMOD "https://github.com/jadddxx/sing-a-song/tree/master/node_modules/"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px;
    classDef uiAssets fill:#bbf,stroke:#333,stroke-width:1px;
    classDef browserAPI fill:#ffb,stroke:#333,stroke-width:1px;
    classDef logic fill:#bfb,stroke:#333,stroke-width:1px;
    classDef server fill:#fbb,stroke:#333,stroke-width:1px;
    classDef build fill:#ddd,stroke:#333,stroke-width:1px;
```
