# harshsandhu44/mood-sync architecture

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

- Interactive diagram: https://gitdiagram.com/harshsandhu44/mood-sync
- Repository: https://github.com/harshsandhu44/mood-sync

## Overview

##### Project Type and Purpose
- This is a client-centric Next.js 13 “app router” project focused on generating and controlling audio in the browser.
- Purpose: let users select moods (e.g., calm, focus) and render corresponding soundscapes via the Web Audio API (and optional libraries like Tone.js or p5.js).

##### File Structure
- Top-level Next.js config files (next.config.ts, postcss.config.mjs, eslint.config.mjs) govern build & linting.
- public/ contains static assets (manifest, browserconfig).
- src/app/ holds Next.js page and layout components (app router).
- src/components/ contains:
– Core UI: MoodSelector, SoundTypeSelector, AudioControls, AudioVisualizer, PlaybackButton, SafetyWarning, etc.
– Providers: root-provider (app-wide context), theme-provider.
– UI primitives: accordion, button, dialog, slider, etc. (your custom component library).
- src/hooks/ encapsulates logic: useAudioEngine (bridges UI to Web Audio API), use-mobile, useCustomStyles.
- src/lib/ utilities (fonts loading, generic utils).
- src/constants/ (moodFrequencies.ts) holds mapping of moods→frequencies.
- src/types/ defines TypeScript types for audio and application data.

##### Pull Architecture Insights from the README
- Entire audio graph runs in the browser via Web Audio API (possibly augmented by Tone.js or p5.js).
- UI/UX emphasizes mood selection → algorithmic sound generation.
- No server-side API routes—only static generation/SSG or SSR for pages. All audio logic is client-side.

##### Main Components & Relationships
a. Components:
- User’s Browser (client environment)
- Next.js App Router & Page/Layout (entry point)
- React Component Tree (MoodSelector, AudioControls, AudioVisualizer, etc.)
- Context Providers (theme, root state)
- Hooks/Services Layer (useAudioEngine orchestrates audio graph; useCustomStyles for theming; etc.)
- Web Audio API (AudioContext, OscillatorNode, GainNode, Filters)
- (Optional) Audio Libraries: Tone.js or p5.js add higher-level scheduling or synthesis features
- Static Assets & Constants (CSS, images, moodFrequencies, fonts)
b. Interactions & Data Flows:
1. User interacts with UI → triggers React handlers.
2. Handlers invoke custom hooks (useAudioEngine) through context.
3. Hook builds/updates an AudioContext graph (oscillators, binaural beats, isochronic tones).
4. Web Audio API outputs sound to client device.
5. UI reading of state (e.g., current frequency, playback status) flows back via context to re-render controls & visualizer.
c. Architectural Patterns:
- Component-based architecture (atomic UI components + providers).
- Hook-driven service layer encapsulating side-effects (audio generation).
- Next.js App Router for page/layout composition.
d. Key Technologies & Frameworks:
- Next.js 13 (React 18, App Router)
- TypeScript
- Web Audio API
- Custom React Hooks
- Tailwind/PostCSS (global styling)
- UI primitives (Radix-style components)
- Optional: Tone.js, p5.js for advanced synthesis

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Next.js App Router" 
        Layout["layout.tsx"] 
        Page["page.tsx"] 
        GlobalsCss["globals.css"]
    end

    subgraph "Static Assets & Config" 
        Manifest["manifest.json"] 
        BrowserConfig["browserconfig.xml"]
        NextConfig["next.config.ts"] 
        PostCSS["postcss.config.mjs"] 
        ESLint["eslint.config.mjs"]
    end

    subgraph "UI Components" 
        MoodSelector["MoodSelector"] 
        SoundTypeSelector["SoundTypeSelector"] 
        AudioControls["AudioControls"] 
        AudioVisualizer["AudioVisualizer"] 
        PlaybackButton["PlaybackButton"] 
        SafetyWarning["SafetyWarning"] 
        HeadphoneNotice["HeadphoneNotice"] 
        InstallPrompt["install-prompt"]
        UIPrimitives["UI Primitives"]
    end

    subgraph "Context Providers" 
        RootProvider["RootProvider"] 
        ThemeProvider["ThemeProvider"]
    end

    subgraph "Hooks & Services" 
        useAudioEngine["useAudioEngine"] 
        useMobile["use-mobile"] 
        useCustomStyles["useCustomStyles"]
    end

    subgraph "Utilities & Constants" 
        MoodFrequencies["moodFrequencies.ts"] 
        TypesAudio["audio.ts"] 
        FontLoader["fonts.ts"] 
        Utils["utils.ts"]
    end

    subgraph "Browser APIs & Libraries" 
        WebAudioAPI["Web Audio API"] 
        ToneJS["Tone.js"] 
        p5JS["p5.js"]
    end

    Output["Audio Output"]

    %% Relationships
    Layout -->|renders| Page
    Page -->|uses| RootProvider
    Page -->|loads| ThemeProvider
    RootProvider -->|wraps| UIComponents["UI Components"]
    ThemeProvider -->|wraps| UIComponents
    UIPrimitives -->|used by| MoodSelector
    UIPrimitives -->|used by| SoundTypeSelector
    UIPrimitives -->|used by| AudioControls
    UIPrimitives -->|used by| AudioVisualizer
    UIPrimitives -->|used by| PlaybackButton
    UIPrimitives -->|used by| SafetyWarning
    UIPrimitives -->|used by| HeadphoneNotice
    UIPrimitives -->|used by| InstallPrompt

    UIComponents -->|user interactions| useAudioEngine
    UIComponents -->|layout info| useCustomStyles
    UIComponents -->|detect device| useMobile

    useAudioEngine -->|reads| MoodFrequencies
    useAudioEngine -->|uses types| TypesAudio
    useCustomStyles -->|uses| FontLoader
    useCustomStyles -->|uses| Utils

    useAudioEngine -->|drives| WebAudioAPI
    useAudioEngine -->|optionally via| ToneJS
    useAudioEngine -->|optionally via| p5JS

    WebAudioAPI -->|outputs| Output

    %% Click Events
    click Layout "https://github.com/harshsandhu44/mood-sync/blob/main/src/app/layout.tsx"
    click Page "https://github.com/harshsandhu44/mood-sync/blob/main/src/app/page.tsx"
    click GlobalsCss "https://github.com/harshsandhu44/mood-sync/blob/main/src/app/globals.css"
    click Manifest "https://github.com/harshsandhu44/mood-sync/blob/main/public/manifest.json"
    click BrowserConfig "https://github.com/harshsandhu44/mood-sync/blob/main/public/browserconfig.xml"
    click NextConfig "https://github.com/harshsandhu44/mood-sync/blob/main/next.config.ts"
    click PostCSS "https://github.com/harshsandhu44/mood-sync/blob/main/postcss.config.mjs"
    click ESLint "https://github.com/harshsandhu44/mood-sync/blob/main/eslint.config.mjs"
    click MoodSelector "https://github.com/harshsandhu44/mood-sync/blob/main/src/components/MoodSelector.tsx"
    click SoundTypeSelector "https://github.com/harshsandhu44/mood-sync/blob/main/src/components/SoundTypeSelector.tsx"
    click AudioControls "https://github.com/harshsandhu44/mood-sync/blob/main/src/components/AudioControls.tsx"
    click AudioVisualizer "https://github.com/harshsandhu44/mood-sync/blob/main/src/components/AudioVisualizer.tsx"
    click PlaybackButton "https://github.com/harshsandhu44/mood-sync/blob/main/src/components/PlaybackButton.tsx"
    click SafetyWarning "https://github.com/harshsandhu44/mood-sync/blob/main/src/components/SafetyWarning.tsx"
    click HeadphoneNotice "https://github.com/harshsandhu44/mood-sync/blob/main/src/components/HeadphoneNotice.tsx"
    click InstallPrompt "https://github.com/harshsandhu44/mood-sync/blob/main/src/components/install-prompt.tsx"
    click RootProvider "https://github.com/harshsandhu44/mood-sync/blob/main/src/components/providers/root-provider.tsx"
    click ThemeProvider "https://github.com/harshsandhu44/mood-sync/blob/main/src/components/providers/theme-provider.tsx"
    click UIPrimitives "https://github.com/harshsandhu44/mood-sync/tree/main/src/components/ui/"
    click useAudioEngine "https://github.com/harshsandhu44/mood-sync/blob/main/src/hooks/useAudioEngine.ts"
    click useMobile "https://github.com/harshsandhu44/mood-sync/blob/main/src/hooks/use-mobile.ts"
    click useCustomStyles "https://github.com/harshsandhu44/mood-sync/blob/main/src/hooks/useCustomStyles.ts"
    click MoodFrequencies "https://github.com/harshsandhu44/mood-sync/blob/main/src/constants/moodFrequencies.ts"
    click TypesAudio "https://github.com/harshsandhu44/mood-sync/blob/main/src/types/audio.ts"
    click FontLoader "https://github.com/harshsandhu44/mood-sync/blob/main/src/lib/fonts.ts"
    click Utils "https://github.com/harshsandhu44/mood-sync/blob/main/src/lib/utils.ts"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085;
    classDef service fill:#d4edda,stroke:#155724;
    classDef api fill:#fff3cd,stroke:#856404;
    classDef static fill:#e2e3e5,stroke:#6c757d;

    class MoodSelector,SoundTypeSelector,AudioControls,AudioVisualizer,PlaybackButton,SafetyWarning,HeadphoneNotice,InstallPrompt,UIPrimitives ui;
    class useAudioEngine,useMobile,useCustomStyles service;
    class WebAudioAPI,ToneJS,p5JS api;
    class Manifest,BrowserConfig,NextConfig,PostCSS,ESLint,MoodFrequencies,TypesAudio,FontLoader,Utils static;
```
