# krishnanx/noctune architecture

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

- Interactive diagram: https://gitdiagram.com/krishnanx/noctune
- Repository: https://github.com/krishnanx/noctune

## Overview

##### Main Components
a. Mobile Client (React Native)
- UI Layer: Pages (Home, Search, Player, etc.) & Reusable Components
- Navigation Module: RootStack, AuthStack, MainTab, Universal
- State Management: Redux Store with slices (Auth, Music, Playlist, Download, Timer, Theme, User, Keyboard)
- Local Assets & Media Loader (AudioLoader, Waveform, etc.)
- WebSocket Client for real-time events
- Native Bridge: iOS (AppDelegate, Swift/Objective-C) & Android (MainActivity, Kotlin)
b. Backend Services
- Authentication & User API (Express.js)
- Music Metadata & Streaming API (FastAPI)
- Real-Time Events Server (WebSocket endpoint)
c. Data Layer
- Supabase (PostgreSQL) for user data, playlists, preferences
- Cloudflare CDN for caching audio streams and static assets

##### Relationships & Data Flows
- From Mobile Client → Backend REST APIs (HTTP/HTTPS) for login, search, playlist CRUD
- Mobile Client ↔ WebSocket Server for live updates (e.g., collaborative queue)
- Backend → Supabase for database reads/writes
- Backend → Cloudflare for publishing/caching audio streams

##### Architectural Patterns
- Single-Page Application pattern inside React Native with Redux for state centralization
- Modular Navigation (stack + tabs) for auth vs. main flows
- Separation of concerns: UI Components ←→ Business Logic (Redux thunks) ←→ API Layer
- Native–JavaScript bridge: React Native core mediates between JS code and native modules

##### Incorporate Technologies & Frameworks
- WebSocket library and key slices (AuthThunk, MusicSlice, DownloadSlice) where they live

##### Detailed Component Breakdown (inside “Mobile App” container)
- State Management: show Redux store with individual slices branching off

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Mobile App Layer
    subgraph "Mobile App" 
        direction TB
        UI["UI Layer"]:::client
        Pages["Pages"]:::client
        Components["Reusable Components"]:::client
        Nav["Navigation Module"]:::client
        RootStack["RootStack"]:::client
        AuthStack["AuthStack"]:::client
        MainTab["MainTab"]:::client
        Universal["Universal"]:::client
        Store["Redux Store"]:::client
        StoreCfg["Store Configuration"]:::client
        AuthThunk["Auth Slice & Thunks"]:::client
        MusicSlice["Music Slice"]:::client
        PlaydataSlice["Playdata Slice"]:::client
        PlaylistSlice["Playlist Slice"]:::client
        DownloadSlice["Download Slice"]:::client
        TimerSlice["Timer Slice"]:::client
        ThemeSlice["Theme Slice"]:::client
        UserSlice["User Slice"]:::client
        KeyboardSlice["Keyboard Slice"]:::client
        Assets["Local Assets & Media Loader"]:::client
        AudioLoader["AudioLoader"]:::client
        Waveform["Waveform Component"]:::client
        WSClient["WebSocket Client"]:::client
        Native["Native Bridge"]:::client
        iOS["iOS (AppDelegate)"]:::client
        AndroidAct["Android MainActivity"]:::client
        AndroidApp["Android Application"]:::client
    end

    %% Backend Services Layer
    subgraph "Backend Services"
        direction TB
        AuthAPI["Authentication & User API\n(Express.js)"]:::api
        MusicAPI["Music Metadata & Streaming API\n(FastAPI)"]:::api
        WSrv["Real-Time Events Server\n(WebSocket)"]:::api
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Supabase[(Supabase\nPostgreSQL)]:::db
        Cloudflare((Cloudflare CDN)):::external
    end

    %% Connections
    UI --> Pages
    UI --> Components
    Nav --> RootStack
    Nav --> AuthStack
    Nav --> MainTab
    Nav --> Universal
    Store --> StoreCfg
    StoreCfg --> AuthThunk
    StoreCfg --> MusicSlice
    StoreCfg --> PlaydataSlice
    StoreCfg --> PlaylistSlice
    StoreCfg --> DownloadSlice
    StoreCfg --> TimerSlice
    StoreCfg --> ThemeSlice
    StoreCfg --> UserSlice
    StoreCfg --> KeyboardSlice
    Assets --> AudioLoader
    Assets --> Waveform
    MobileAppClick[InvisibleAnchor] --> UI

    %% Flows
    UI -->|"REST API"| AuthAPI
    UI -->|"REST API"| MusicAPI
    WSClient -.->|"WebSocket"| WSrv
    AuthAPI -->|"reads/writes"| Supabase
    MusicAPI -->|"reads/writes"| Supabase
    MusicAPI -->|"publishes streams"| Cloudflare

    %% Legend
    subgraph "Legend"
        direction TB
        C1["Client Components"]:::client
        C2["API Servers"]:::api
        C3["Databases"]:::db
        C4["External CDN"]:::external
        A1["Solid arrow: REST"] 
        A2["Dashed arrow: WebSocket"]
    end

    %% Click Events
    click Pages "https://github.com/krishnanx/noctune/tree/main/src/pages"
    click Components "https://github.com/krishnanx/noctune/tree/main/src/Components"
    click RootStack "https://github.com/krishnanx/noctune/blob/main/Navigation/RootStackNavigator.js"
    click AuthStack "https://github.com/krishnanx/noctune/blob/main/Navigation/AuthStack.js"
    click MainTab "https://github.com/krishnanx/noctune/blob/main/Navigation/MainTab.js"
    click Universal "https://github.com/krishnanx/noctune/blob/main/Navigation/Universal.js"
    click StoreCfg "https://github.com/krishnanx/noctune/blob/main/Store/store.js"
    click AuthThunk "https://github.com/krishnanx/noctune/blob/main/Store/AuthThunk.js"
    click MusicSlice "https://github.com/krishnanx/noctune/blob/main/Store/MusicSlice.js"
    click PlaydataSlice "https://github.com/krishnanx/noctune/blob/main/Store/Playdataslice.js"
    click PlaylistSlice "https://github.com/krishnanx/noctune/blob/main/Store/PlaylistSlice.js"
    click DownloadSlice "https://github.com/krishnanx/noctune/blob/main/Store/DownloadSlice.js"
    click TimerSlice "https://github.com/krishnanx/noctune/blob/main/Store/TimerSlice.js"
    click ThemeSlice "https://github.com/krishnanx/noctune/blob/main/Store/ThemeSlice.js"
    click UserSlice "https://github.com/krishnanx/noctune/blob/main/Store/UserSlice.js"
    click KeyboardSlice "https://github.com/krishnanx/noctune/blob/main/Store/KeyboardSlice.js"
    click AudioLoader "https://github.com/krishnanx/noctune/blob/main/src/functions/Audioloader.jsx"
    click Waveform "https://github.com/krishnanx/noctune/blob/main/src/Components/Waveform.jsx"
    click WSClient "https://github.com/krishnanx/noctune/blob/main/src/Websocket/Websocket.js"
    click iOS "https://github.com/krishnanx/noctune/blob/main/ios/Noctune/AppDelegate.h"
    click iOS "https://github.com/krishnanx/noctune/blob/main/ios/Noctune/AppDelegate.mm"
    click AndroidAct "https://github.com/krishnanx/noctune/blob/main/android/app/src/main/java/com/krishnanx/Noctune/MainActivity.kt"
    click AndroidApp "https://github.com/krishnanx/noctune/blob/main/android/app/src/main/java/com/krishnanx/Noctune/MainApplication.kt"

    %% Styles
    classDef client fill:#add8e6,stroke:#000,stroke-width:1px
    classDef api fill:#ffa500,stroke:#000,stroke-width:1px
    classDef db fill:#90ee90,stroke:#000,stroke-width:1px
    classDef external fill:#d3b3ff,stroke:#000,stroke-width:1px
    class Pages,Components,RootStack,AuthStack,MainTab,Universal,StoreCfg,AuthThunk,MusicSlice,PlaydataSlice,PlaylistSlice,DownloadSlice,TimerSlice,ThemeSlice,UserSlice,KeyboardSlice,AudioLoader,Waveform,WSClient,iOS,AndroidAct,AndroidApp client
    class AuthAPI,MusicAPI,WSrv api
    class Supabase db
    class Cloudflare external
```
