# sa1ava/puma architecture

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

- Interactive diagram: https://gitdiagram.com/sa1ava/puma
- Repository: https://github.com/sa1ava/puma

## Overview

##### Project type and purpose
- Project type: Front-end SPA (no backend).
- Purpose: A browser‐based music player that reads a local tracks.json, renders UI controls (play/pause, progress bar, playlist selector), and manages playback state entirely in the client.

##### File structure
- Top‐level config:
– vite.config.ts, tsconfig*.json, eslint.config.js, package.json, pnpm-lock.yaml – define build, linting, TS setup and dependencies.
- Public assets:
– index.html (app shell), public/ (static files).
- Source code (src/):
– main.tsx: application entry, mounts React root.
– App.tsx + App.css: top‐level layout.
– assets/: style.css, tracks.json (data source for playlist).
– components/: Player, PlayerControls, PlayerControlButton, PlayerProgressBar, PlaylistSelector – UI building blocks.
– utils/: utility functions (e.g., time formatting, audio helpers).
– types/: TS definitions for Track and Progress.

##### Key architectural patterns & tech
- Component-based UI (React).
- Unidirectional data flow (state propagated top‐down from App → Player → controls).
- Build & dev server provided by Vite (fast HMR).
- Static JSON as data store (no network calls).
- CSS modularization (component CSS + global CSS).

##### Main components & their interactions
a. Browser (Client)
– Renders index.html, loads bundled JS/CSS.
b. Vite Dev / Production Server
– Serves static assets & bundles.
c. React App
– App.tsx holds global state (currentTrack, isPlaying, progress).
– Player component orchestrates HTMLMediaElement (Audio).
– Child components (PlayerControls, ProgressBar, PlaylistSelector) receive props/events to modify state.
– utils.ts provides helper functions.
d. Data Source
– tracks.json loaded at startup or via import.
e. Build Pipeline
– vite.config.ts defines asset transforms, TS/JSX compilation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External / Build Systems
    subgraph "Build & Dev Environment"
        direction TB
        ViteServer["Vite Dev Server"]:::external
        ViteProd["Vite Production Bundler"]:::external
    end

    %% Client Browser
    Browser["Browser / Client"]:::external
    ViteServer -->|"Serves index.html & bundles (HTTP GET)"| Browser
    ViteProd -->|"Bundles to dist/ then serves"| Browser

    %% Public Assets
    PublicHTML["index.html"]:::asset
    PublicDir["public/"]:::asset
    Browser --> PublicHTML
    Browser --> PublicDir
    click PublicHTML "https://github.com/sa1ava/puma/blob/main/index.html"
    click PublicDir "https://github.com/sa1ava/puma/tree/main/public/"

    %% React SPA
    subgraph "React SPA" 
        direction TB
        Entry["main.tsx\n(Application Entry)"]:::frontend
        AppContainer["App.tsx\n(App Container)"]:::frontend
        AppStyles["App.css"]:::asset
        Entry --> AppContainer
        click Entry "https://github.com/sa1ava/puma/blob/main/src/main.tsx"
        click AppContainer "https://github.com/sa1ava/puma/blob/main/src/App.tsx"
        click AppStyles "https://github.com/sa1ava/puma/blob/main/src/App.css"

        %% Assets inside SPA
        subgraph "Assets" 
            direction TB
            Tracks["tracks.json"]:::data
            StyleCSS["style.css"]:::asset
            click Tracks "https://github.com/sa1ava/puma/blob/main/src/assets/tracks.json"
            click StyleCSS "https://github.com/sa1ava/puma/blob/main/src/assets/style.css"
        end

        %% Utils & Types
        subgraph "Utilities & Types"
            direction TB
            Utils["utils.ts"]:::util
            TypeTrack["track.ts"]:::type
            TypeProg["progress.ts"]:::type
            click Utils "https://github.com/sa1ava/puma/blob/main/src/utils/utils.ts"
            click TypeTrack "https://github.com/sa1ava/puma/blob/main/src/types/track.ts"
            click TypeProg "https://github.com/sa1ava/puma/blob/main/src/types/progress.ts"
        end

        %% Player Module
        subgraph "Player Module"
            direction TB
            PlayerCore["Player.tsx"]:::component
            PlayerControls["PlayerControls.tsx"]:::component
            PlayerButton["PlayerControlButton.tsx"]:::component
            ProgressBar["PlayerProgressBar.tsx"]:::component
            PlaylistSel["PlaylistSelector.tsx"]:::component
            click PlayerCore "https://github.com/sa1ava/puma/blob/main/src/components/Player.tsx"
            click PlayerControls "https://github.com/sa1ava/puma/blob/main/src/components/PlayerControls.tsx"
            click PlayerButton "https://github.com/sa1ava/puma/blob/main/src/components/PlayerControlButton.tsx"
            click ProgressBar "https://github.com/sa1ava/puma/blob/main/src/components/PlayerProgressBar.tsx"
            click PlaylistSel "https://github.com/sa1ava/puma/blob/main/src/components/PlaylistSelector.tsx"
        end

        %% Typescript Vite env
        ViteEnv["vite-env.d.ts"]:::type
        click ViteEnv "https://github.com/sa1ava/puma/blob/main/src/vite-env.d.ts"
    end

    %% Data flows within SPA
    Tracks -->|"load tracks.json"| AppContainer
    AppContainer -->|"props: currentTrack, isPlaying, progress"| PlayerCore
    PlayerControls -->|"play/pause events"| AppContainer
    PlaylistSel -->|"track selection event"| AppContainer
    PlayerCore -->|"controls HTML5 Audio API"| ProgressBar

    %% Build Config & Metadata
    subgraph "Project Config"
        direction TB
        ViteConfig["vite.config.ts"]:::config
        TSConfig["tsconfig.json\n(tsconfig.app.json, tsconfig.node.json)"]:::config
        ESLint["eslint.config.js"]:::config
        PackageJSON["package.json\npnpm-lock.yaml"]:::config
        click ViteConfig "https://github.com/sa1ava/puma/blob/main/vite.config.ts"
        click TSConfig "https://github.com/sa1ava/puma/blob/main/tsconfig.json"
        click ESLint "https://github.com/sa1ava/puma/blob/main/eslint.config.js"
        click PackageJSON "https://github.com/sa1ava/puma/blob/main/package.json"
    end

    %% Legend
    subgraph "Legend"
        direction TB
        ext["External / Server"]:::external
        front["Front-end Module"]:::frontend
        comp["Component"]:::component
        utilc["Utility"]:::util
        dataico["Data Source"]:::data
        assetico["Asset / Styles"]:::asset
        typeico["TypeScript Definitions"]:::type
        configico["Config / Build"]:::config
    end

    classDef external fill:#f9f,stroke:#333,stroke-dasharray: 5 5;
    classDef frontend fill:#ccf,stroke:#333;
    classDef component fill:#cfc,stroke:#333;
    classDef util fill:#fcf,stroke:#333;
    classDef data fill:#ffc,stroke:#333,stroke-dasharray: 2 2;
    classDef asset fill:#cff,stroke:#333;
    classDef type fill:#eef,stroke:#333;
    classDef config fill:#fdd,stroke:#333;
```
