# nukeop/nuclear architecture

> Architecture diagram of the GitHub repository nukeop/nuclear, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nukeop/nuclear
- Repository: https://github.com/nukeop/nuclear

## Overview

##### Main Application Components (Top Level)
- Frontend (Electron Renderer Process)
- Backend (Electron Main Process)
- Core Services
- External APIs/Services

##### Frontend Layer
- React Components (/packages/app/app/components)
- Redux Store (/packages/app/app/store)
- UI Components Library (/packages/ui)
- State Management
- Actions (/packages/app/app/actions)
- Reducers (/packages/app/app/reducers)
- Selectors (/packages/app/app/selectors)

##### Backend Layer
- Main Process Services (/packages/main/src/services)
- HTTP Server
- IPC Communication
- System API
- Local Library Scanner
- Download Manager
- Discord Integration
- Configuration Management

##### Core Services Layer (/packages/core)
- Plugin System
- Stream Providers (YouTube, SoundCloud, etc.)
- Lyrics Providers
- Metadata Providers
- REST Clients
- Last.fm
- Discogs
- Spotify
- YouTube
- Local File Management
- Settings Management

##### Data Flow
- IPC communication between frontend and backend
- API calls to external services
- Plugin system interactions
- State management flow
- Event handling paths

##### External Services Integration
- Streaming Sources
- YouTube
- Jamendo
- Audius
- SoundCloud
- Metadata Sources
- Last.fm
- Discogs
- Lyrics Services
- SponsorBlock Integration

##### Additional Elements
- Database/Storage (Local library, playlists)
- Configuration Management
- Plugin Architecture
- Security Boundaries
- Error Handling Flow

Key Architectural Patterns to Highlight:
- Event-driven architecture (IPC communication)
- Plugin-based system for extensibility
- Redux for state management
- Service-oriented architecture for backend services
- Component-based UI architecture

- Component types
- Data flow directions
- Critical paths
- Integration points

##### Data flow patterns

This will provide a clear understanding of Nuclear's architecture while maintaining the right level of detail for a principal software engineer to understand the system's components and their interactions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef backend fill:#2ecc71,stroke:#27ae60,color:white
    classDef core fill:#f1c40f,stroke:#f39c12,color:black
    classDef external fill:#9b59b6,stroke:#8e44ad,color:white
    classDef storage fill:#95a5a6,stroke:#7f8c8d,color:white
    
    %% Main Application Structure
    subgraph Frontend
        ReactComponents["React Components"]:::frontend
        ReduxStore["Redux Store"]:::frontend
        UILib["UI Components Library"]:::frontend
        
        subgraph StateManagement
            Actions["Actions"]:::frontend
            Reducers["Reducers"]:::frontend
            Selectors["Selectors"]:::frontend
        end
    end
    
    subgraph Backend
        MainProcess["Main Process Services"]:::backend
        HTTPServer["HTTP Server"]:::backend
        IPCComm["IPC Communication"]:::backend
        SystemAPI["System API"]:::backend
        LibScanner["Library Scanner"]:::backend
        DownloadMgr["Download Manager"]:::backend
        DiscordInt["Discord Integration"]:::backend
        ConfigMgmt["Configuration Management"]:::backend
    end
    
    subgraph CoreServices
        PluginSystem["Plugin System"]:::core
        RESTClients["REST Clients"]:::core
        LocalFileMgmt["Local File Management"]:::core
        SettingsMgmt["Settings Management"]:::core
        
        subgraph Plugins
            StreamProviders["Stream Providers"]:::core
            MetadataProviders["Metadata Providers"]:::core
            LyricsProviders["Lyrics Providers"]:::core
        end
    end
    
    subgraph ExternalServices
        YouTube["YouTube"]:::external
        Jamendo["Jamendo"]:::external
        Audius["Audius"]:::external
        SoundCloud["SoundCloud"]:::external
        LastFM["Last.fm"]:::external
        Discogs["Discogs"]:::external
        SponsorBlock["SponsorBlock"]:::external
    end
    
    %% Data Storage
    LocalLibrary[("Local Library")]:::storage
    ListeningHistory[("Listening History")]:::storage
    
    %% Relationships
    ReactComponents <--> ReduxStore
    ReduxStore <--> StateManagement
    ReactComponents <--> UILib
    Frontend <--> IPCComm
    IPCComm <--> Backend
    PluginSystem <--> StreamProviders
    PluginSystem <--> MetadataProviders
    PluginSystem <--> LyricsProviders
    RESTClients <--> ExternalServices
    LibScanner --> LocalLibrary
    MainProcess --> ListeningHistory
    
    %% Click Events
    click ReactComponents "https://github.com/nukeop/nuclear/tree/master/packages/app/app/components"
    click ReduxStore "https://github.com/nukeop/nuclear/tree/master/packages/app/app/store"
    click UILib "https://github.com/nukeop/nuclear/tree/master/packages/ui/lib/components"
    click Actions "https://github.com/nukeop/nuclear/tree/master/packages/app/app/actions"
    click Reducers "https://github.com/nukeop/nuclear/tree/master/packages/app/app/reducers"
    click Selectors "https://github.com/nukeop/nuclear/tree/master/packages/app/app/selectors"
    click MainProcess "https://github.com/nukeop/nuclear/tree/master/packages/main/src/services"
    click HTTPServer "https://github.com/nukeop/nuclear/tree/master/packages/main/src/services/http"
    click IPCComm "https://github.com/nukeop/nuclear/tree/master/packages/main/src/services/ipc"
    click SystemAPI "https://github.com/nukeop/nuclear/tree/master/packages/main/src/services/system-api"
    click LibScanner "https://github.com/nukeop/nuclear/tree/master/packages/main/src/services/library-scanner"
    click DownloadMgr "https://github.com/nukeop/nuclear/tree/master/packages/main/src/services/download"
    click DiscordInt "https://github.com/nukeop/nuclear/tree/master/packages/main/src/services/discord"
    click ConfigMgmt "https://github.com/nukeop/nuclear/tree/master/packages/main/src/services/config"
    click PluginSystem "https://github.com/nukeop/nuclear/tree/master/packages/core/src/plugins"
    click RESTClients "https://github.com/nukeop/nuclear/tree/master/packages/core/src/rest"
    click LocalFileMgmt "https://github.com/nukeop/nuclear/tree/master/packages/core/src/helpers"
    click SettingsMgmt "https://github.com/nukeop/nuclear/tree/master/packages/core/src/settings"
    click StreamProviders "https://github.com/nukeop/nuclear/tree/master/packages/core/src/plugins/stream"
    click MetadataProviders "https://github.com/nukeop/nuclear/tree/master/packages/core/src/plugins/meta"
    click LyricsProviders "https://github.com/nukeop/nuclear/tree/master/packages/core/src/plugins/lyrics"
    click LocalLibrary "https://github.com/nukeop/nuclear/tree/master/packages/main/src/services/local-library"
    click ListeningHistory "https://github.com/nukeop/nuclear/tree/master/packages/main/src/services/listening-history"
```
