# codedeficient/audiosphere architecture

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

- Interactive diagram: https://gitdiagram.com/codedeficient/audiosphere
- Repository: https://github.com/codedeficient/audiosphere

## Overview

##### Project type and purpose
- AudioSphere is a full-stack, web-based music player built on Next.js.
- It serves a React-based UI in the browser, provides a Node-based API route for listing audio tracks, and hosts static audio assets and auth handlers via Firebase (deployed on Vercel).
- It leverages Tone.js in the client for real-time audio processing and Nix/GitHub Actions for reproducible builds and CI/CD.

##### File structure
Top-level directories and files reveal the following logical layers:
- src/app – Next.js App Router folder (page.tsx, layout.tsx, API routes under app/api).
- src/components – React UI components (MusicPlayer, PlaybackControls, SphereVisualizer, Playlist, plus a UI library).
- src/hooks & src/lib – custom React hooks and utility functions.
- public/audio – static audio files.
- public/_auth – static auth handlers/experiments.
- .github/workflows & .github/scripts – CI/CD pipeline and scripts.
- .idx/dev.nix – Nix development shell definition.
Configuration and build files (.eslintrc.json, tsconfig.json, next.config.ts, Tailwind/PostCSS configs, package.json) confirm a Next.js + TypeScript + Tailwind CSS stack.

##### Extract additional insights from the README
- The project already defines four logical layers: Client, Server/Build, Hosting/Storage, and DevOps.
- Key technologies: Next.js (SSG/SSR), React components, Tone.js (client audio), Firebase Hosting, GitHub Actions, Nix, Vercel deployment.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Layer"
        Browser["Browser (User)"]:::frontend
        page["page.tsx"]:::frontend
        layout["layout.tsx"]:::frontend
        MusicPlayer["MusicPlayer Component"]:::frontend
        PlaybackControls["PlaybackControls Component"]:::frontend
        SphereVisualizer["SphereVisualizer (Tone.js)"]:::frontend
        Playlist["Playlist Component"]:::frontend
        ClientOnly["Client-Only Wrapper"]:::frontend
        UI_Lib["UI Component Library"]:::frontend
        HookMobile["use-mobile Hook"]:::frontend
        HookToast["use-toast Hook"]:::frontend
        Utils["Utility Functions"]:::frontend
        GlobalsCSS["globals.css"]:::frontend
        TailwindConfig["tailwind.config.ts"]:::frontend
        PostCSSConfig["postcss.config.mjs"]:::frontend
        ToneJS["Tone.js Audio Engine"]:::frontend
    end

    subgraph "Server/Build Layer"
        NextJSServer["Next.js Server"]:::backend
        AudioAPI["GET /api/audio-list"]:::backend
        NextConfig["next.config.ts"]:::backend
        TSConfig["tsconfig.json"]:::backend
    end

    subgraph "Hosting/Storage Layer"
        FirebaseHosting["Firebase Hosting"]:::storage
        Vercel["Vercel Deployment"]:::storage
        AudioAssets["Static Audio Assets"]:::storage
        AuthHandlers["Static Auth Handlers"]:::storage
        FirebaseJSON["firebase.json"]:::storage
        Firebaserc[".firebaserc"]:::storage
    end

    subgraph "DevOps Layer"
        GHWorkflow["GitHub Actions Workflow"]:::devops
        RoadmapScript["Update Roadmap Script"]:::devops
        NixShell["Nix Dev Shell"]:::devops
    end

    %% Client interactions
    Browser --> page
    page --> layout
    layout --> MusicPlayer
    MusicPlayer --> PlaybackControls
    MusicPlayer --> SphereVisualizer
    SphereVisualizer --> ToneJS
    layout --> Playlist
    layout --> ClientOnly
    MusicPlayer --> UI_Lib
    PlaybackControls --> UI_Lib
    ClientOnly --> UI_Lib
    layout --> HookMobile
    layout --> HookToast
    layout --> Utils
    layout --> GlobalsCSS
    layout --> TailwindConfig
    layout --> PostCSSConfig

    %% API and storage
    Playlist --> AudioAPI
    AudioAPI --> AudioAssets
    Browser --> AudioAssets
    Browser --> AuthHandlers

    %% Server/Build relations
    layout --> NextJSServer
    AudioAPI --> NextJSServer
    NextJSServer --> NextConfig
    NextJSServer --> TSConfig

    %% Hosting config
    FirebaseHosting --> FirebaseJSON
    FirebaseHosting --> Firebaserc

    %% DevOps flows
    GHWorkflow --> FirebaseHosting
    GHWorkflow --> Vercel
    GHWorkflow --> RoadmapScript
    NixShell --> GHWorkflow

    %% Click Events
    click page "https://github.com/codedeficient/audiosphere/blob/main/src/app/page.tsx"
    click layout "https://github.com/codedeficient/audiosphere/blob/main/src/app/layout.tsx"
    click MusicPlayer "https://github.com/codedeficient/audiosphere/blob/main/src/components/MusicPlayer.tsx"
    click PlaybackControls "https://github.com/codedeficient/audiosphere/blob/main/src/components/PlaybackControls.tsx"
    click SphereVisualizer "https://github.com/codedeficient/audiosphere/blob/main/src/components/SphereVisualizer.tsx"
    click Playlist "https://github.com/codedeficient/audiosphere/blob/main/src/components/Playlist.tsx"
    click ClientOnly "https://github.com/codedeficient/audiosphere/blob/main/src/components/ClientOnly.tsx"
    click UI_Lib "https://github.com/codedeficient/audiosphere/tree/main/src/components/ui/"
    click HookMobile "https://github.com/codedeficient/audiosphere/blob/main/src/hooks/use-mobile.tsx"
    click HookToast "https://github.com/codedeficient/audiosphere/blob/main/src/hooks/use-toast.tsx"
    click Utils "https://github.com/codedeficient/audiosphere/blob/main/src/lib/utils.ts"
    click GlobalsCSS "https://github.com/codedeficient/audiosphere/blob/main/src/app/globals.css"
    click TailwindConfig "https://github.com/codedeficient/audiosphere/blob/main/tailwind.config.ts"
    click PostCSSConfig "https://github.com/codedeficient/audiosphere/blob/main/postcss.config.mjs"
    click AudioAPI "https://github.com/codedeficient/audiosphere/blob/main/src/app/api/audio-list/route.ts"
    click NextConfig "https://github.com/codedeficient/audiosphere/blob/main/next.config.ts"
    click TSConfig "https://github.com/codedeficient/audiosphere/blob/main/tsconfig.json"
    click AudioAssets "https://github.com/codedeficient/audiosphere/tree/main/public/audio/"
    click AuthHandlers "https://github.com/codedeficient/audiosphere/tree/main/public/_auth/"
    click FirebaseJSON "https://github.com/codedeficient/audiosphere/blob/main/firebase.json"
    click Firebaserc "https://github.com/codedeficient/audiosphere/blob/main/.firebaserc"
    click GHWorkflow "https://github.com/codedeficient/audiosphere/blob/main/.github/workflows/roadmap-progress.yml"
    click RoadmapScript "https://github.com/codedeficient/audiosphere/blob/main/.github/scripts/update-roadmap-checkbox.js"
    click NixShell "https://github.com/codedeficient/audiosphere/blob/main/.idx/dev.nix"

    classDef frontend fill:#D6E4FF,stroke:#333,stroke-width:1px;
    classDef backend fill:#DFF2BF,stroke:#333,stroke-width:1px;
    classDef storage fill:#FFE4B5,stroke:#333,stroke-width:1px;
    classDef devops stroke:#888,stroke-dasharray:5 5,fill:#f5f5f5;
```
