# casantosmu/audiodeck architecture

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

- Interactive diagram: https://gitdiagram.com/casantosmu/audiodeck
- Repository: https://github.com/casantosmu/audiodeck

## Overview

##### Project type and purpose
- From the file tree and README, AudioDeck is a full-stack, self-hosted web application.
- Frontend: a React/TypeScript single-page app built with Vite.
- Backend: a Go HTTP API serving static assets, listing media files, and reading audio data from a read-only volume.
- Purpose: let users browse their local music library, fetch audio files, and generate spectrograms entirely in the browser.

##### File structure
- Top level: Dockerfile and dockerignore (container build & runtime), README/license.
- backend/:
- cmd/api/: HTTP entrypoint (main.go, routes.go, handlers.go, middleware.go)
- internal/media/: logic to open, decode, and probe audio files (decode.go, format.go)
- go.mod/sum: Go module definitions
- frontend/:
- public & index.html: static shell
- src/: React app (App.tsx, components, context, hooks, core models, utils)
- vite.config.ts & tsconfig*: build config
- package.json & pnpm-lock.yaml: dependencies & scripts
- Absence of a database: file system is the sole “data store.”

##### README for additional insights
- Key features: zero server load for spectrogram generation, path-traversal-safe, Docker-ready.
- Usage: volume mount `/media` from host into the container, expose port 4747.

##### Main components and their interactions
a. Frontend SPA (React/Vite)
- Served as static assets by the Go backend.
- Components: FileBrowser (lists files via API), SpectrogramDisplay (uses Web Audio API to render).
b. Backend HTTP API (Go)
- Serves static files (HTML/CSS/JS).
- Exposes endpoints under `/api/…`:
- GET `/api/files`: directory listing (reads `/media` mount).
- GET `/api/audio/:path`: streams raw audio bytes.
- Internal media package handles audio probing and MIME negotiation.
c. File system volume
- Host directory mounted read-only into container at `/media`.
d. Client processing
- Browser fetches audio chunks, decodes via Web Audio API, computes spectrogram on the client side.
e. Docker container
- Encapsulates backend + static assets + volume mount; orchestrated via Docker Compose.

##### Architectural patterns and design principles
- Single page application (SPA) front/backend separation via REST API.
- Minimal backend responsibilities: serve assets and stream files (thin API layer).
- Client-side heavy lifting (spectrogram generation) for zero server CPU load.
- Secure by design: read-only mounts, middleware guarding against path traversal.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "User’s Browser" 
        direction TB
        Browser["Browser (React SPA)"]:::client
        FileBrowser["FileBrowser Component"]:::client
        Spectrogram["SpectrogramDisplay Component"]:::client
        WebAudio["Web Audio API\nSpectrogram Computation"]:::client
    end

    %% Infrastructure
    subgraph "Docker Compose" 
        direction TB
        subgraph "Docker Container" 
            direction TB
            APIServer["Go API Server\n(port 4747)"]:::server
            Static["Static Asset Serving\nGET / → index.html"]:::server
            APIFiles["GET /api/files\n→ JSON"]:::server
            APIAudio["GET /api/audio/:path\n→ Audio Stream"]:::server
            MediaVolume["Media Volume (/media)"]:::storage
        end
    end

    %% Connections
    Browser -->|"1: GET /"| Static
    Browser -->|"2: GET /api/files"| APIFiles
    FileBrowser -->|"fetch /api/files"| APIFiles
    Browser -->|"3: GET /api/audio/:path"| APIAudio
    Spectrogram -->|"fetch audio bytes"| APIAudio
    Spectrogram -->|decode| WebAudio
    APIServer -->|"reads files"| MediaVolume

    %% Click Events - Frontend
    click Browser "https://github.com/casantosmu/audiodeck/blob/main/frontend/index.html"
    click FileBrowser "https://github.com/casantosmu/audiodeck/blob/main/frontend/src/components/FileBrowser/FileBrowser.tsx"
    click Spectrogram "https://github.com/casantosmu/audiodeck/blob/main/frontend/src/components/SpectrogramDisplay/SpectrogramDisplay.tsx"
    click Browser "https://github.com/casantosmu/audiodeck/blob/main/frontend/vite.config.ts"
    click Browser "https://github.com/casantosmu/audiodeck/blob/main/frontend/package.json"
    click Browser "https://github.com/casantosmu/audiodeck/blob/main/frontend/src/main.tsx"
    click Browser "https://github.com/casantosmu/audiodeck/blob/main/frontend/src/App.tsx"

    %% Click Events - Backend
    click APIServer "https://github.com/casantosmu/audiodeck/blob/main/backend/cmd/api/main.go"
    click APIServer "https://github.com/casantosmu/audiodeck/blob/main/backend/cmd/api/routes.go"
    click APIServer "https://github.com/casantosmu/audiodeck/blob/main/backend/cmd/api/handlers.go"
    click APIServer "https://github.com/casantosmu/audiodeck/blob/main/backend/cmd/api/middleware.go"
    click APIServer "https://github.com/casantosmu/audiodeck/blob/main/backend/cmd/api/dtos.go"
    click APIServer "https://github.com/casantosmu/audiodeck/blob/main/backend/cmd/api/errors.go"
    click APIServer "https://github.com/casantosmu/audiodeck/blob/main/backend/cmd/api/helpers.go"
    click Static "https://github.com/casantosmu/audiodeck/blob/main/backend/cmd/api/ui/index.html"
    click MediaVolume "https://github.com/casantosmu/audiodeck/blob/main/backend/internal/media/decode.go"
    click MediaVolume "https://github.com/casantosmu/audiodeck/blob/main/backend/internal/media/format.go"

    %% Click Events - Docker & Docs
    click APIServer "https://github.com/casantosmu/audiodeck/tree/main/Dockerfile"
    click APIServer "https://github.com/casantosmu/audiodeck/blob/main/.dockerignore"
    click APIServer "https://github.com/casantosmu/audiodeck/blob/main/README.md"
    click APIServer "https://github.com/casantosmu/audiodeck/tree/main/LICENSE"

    %% Styles
    classDef client fill:#B0E0E6,stroke:#333,stroke-width:1px
    classDef server fill:#98FB98,stroke:#333,stroke-width:1px
    classDef storage fill:#FFD580,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
```
