# blackcandy-org/blackcandy architecture

> Architecture diagram of the GitHub repository blackcandy-org/blackcandy, 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/blackcandy-org/blackcandy
- Repository: https://github.com/blackcandy-org/blackcandy

## Overview

##### Main Components Identification

a. Frontend Layer:
- Web Interface (Rails views + JavaScript/Stimulus controllers)
- Mobile Apps (iOS and Android clients)
- PWA Support (manifest.json and service-worker.js)

b. Backend Layer:
- Rails Application Server
- API Controllers (v1 API endpoints)
- Authentication System
- Media Processing Services
- Stream Controllers

c. Storage Layer:
- Database (SQLite/PostgreSQL)
- File Storage (Media files)
- Active Storage (for images)

d. External Services:
- Discogs API Integration
- Nginx (optional for file serving)

**[Mobile Apps/Web Clients] → [Load Balancer/Nginx]**
- ↓
**[Rails Application Server] → [API Controllers]**
- ↓
**[Core Services]**
- Media Processing
- Authentication
- Playlist Management
- Search Service
- ↓
**[Storage Layer]**
- Database
- File Storage
- ↓
**[External Services]**
- Discogs API

##### Key Flows

- User authentication flow
- Media streaming path
- File synchronization process
- Search and filtering operations
- Playlist management
- Cover art retrieval from Discogs

##### Technical Details

Annotations for:
- Port mappings (3000)
- Supported audio formats
- Database adapters
- Storage mount points
- API endpoints structure
- Media processing capabilities

##### Notes Section

Important notes about:
- Scalability options
- Security considerations
- Configuration requirements
- Mobile app integration points

Remember to emphasize the modular nature of the system, showing how components like media processing, authentication, and streaming can be configured or swapped based on deployment needs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        WEB["Web Interface"]
        MOB["Mobile Apps"]
        PWA["PWA Support"]
    end

    subgraph "Application Layer"
        NGINX["Load Balancer/Nginx"]
        RAILS["Rails Application Server"]
        
        subgraph "Core Services"
            AUTH["Authentication System"]
            MEDIA["Media Processing"]
            STREAM["Streaming Service"]
            SYNC["Media Syncing"]
            SEARCH["Search Service"]
            PLAYLIST["Playlist Management"]
            USER["User Management"]
            SETTINGS["Settings Management"]
        end
        
        subgraph "API Layer"
            API["API Controllers v1"]
            FRONT["Frontend Controllers"]
        end
    end
    
    subgraph "Storage Layer"
        DB[(Database)]
        FILES[(File Storage)]
        ACTIVE[(Active Storage)]
    end
    
    subgraph "External Services"
        DISCOGS["Discogs API"]
    end

    %% Relationships
    WEB --> NGINX
    MOB --> NGINX
    PWA --> NGINX
    NGINX --> RAILS
    RAILS --> API
    RAILS --> FRONT
    API --> AUTH
    API --> MEDIA
    API --> STREAM
    API --> SYNC
    API --> SEARCH
    API --> PLAYLIST
    API --> USER
    API --> SETTINGS
    MEDIA --> FILES
    MEDIA --> DB
    STREAM --> FILES
    AUTH --> DB
    PLAYLIST --> DB
    SEARCH --> DB
    USER --> DB
    SETTINGS --> DB
    MEDIA --> ACTIVE
    MEDIA --> DISCOGS

    %% Styling
    classDef frontend fill:#ddf,stroke:#333
    classDef backend fill:#dfd,stroke:#333
    classDef storage fill:#ffd,stroke:#333
    classDef external fill:#eee,stroke:#333

    class WEB,MOB,PWA,FRONT frontend
    class NGINX,RAILS,AUTH,MEDIA,STREAM,SYNC,SEARCH,PLAYLIST,USER,SETTINGS,API backend
    class DB,FILES,ACTIVE storage
    class DISCOGS external

    %% Click events
    click WEB "https://github.com/blackcandy-org/blackcandy/tree/master/app/views/"
    click PWA "https://github.com/blackcandy-org/blackcandy/tree/master/app/views/pwa/"
    click FRONT "https://github.com/blackcandy-org/blackcandy/tree/master/app/javascript/controllers/"
    click API "https://github.com/blackcandy-org/blackcandy/tree/master/app/controllers/api/v1/"
    click AUTH "https://github.com/blackcandy-org/blackcandy/blob/master/app/controllers/sessions_controller.rb"
    click MEDIA "https://github.com/blackcandy-org/blackcandy/blob/master/app/models/media.rb"
    click STREAM "https://github.com/blackcandy-org/blackcandy/blob/master/app/controllers/stream_controller.rb"
    click DB "https://github.com/blackcandy-org/blackcandy/tree/master/db/migrate/"
    click ACTIVE "https://github.com/blackcandy-org/blackcandy/blob/master/db/migrate/20240115020448_create_active_storage_tables.active_storage.rb"
    click DISCOGS "https://github.com/blackcandy-org/blackcandy/blob/master/app/models/integrations/discogs.rb"
    click SYNC "https://github.com/blackcandy-org/blackcandy/blob/master/app/controllers/media_syncing_controller.rb"
    click PLAYLIST "https://github.com/blackcandy-org/blackcandy/blob/master/app/controllers/playlists_controller.rb"
    click SEARCH "https://github.com/blackcandy-org/blackcandy/blob/master/app/controllers/search_controller.rb"
    click USER "https://github.com/blackcandy-org/blackcandy/blob/master/app/controllers/users_controller.rb"
    click SETTINGS "https://github.com/blackcandy-org/blackcandy/blob/master/app/controllers/settings_controller.rb"
```
