# kieraneglin/pinchflat architecture

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

- Interactive diagram: https://gitdiagram.com/kieraneglin/pinchflat
- Repository: https://github.com/kieraneglin/pinchflat

## Overview

##### Main Components Overview
The system should be divided into these primary components:

a. Web Interface Layer
- Phoenix-based web application (lib/pinchflat_web/)
- Controllers for different resources (media items, profiles, sources)
- LiveView components for real-time updates

b. Core Application Layer (lib/pinchflat/)
- Media Management
- Download Management
- Indexing Systems
- Profile Management
- Settings Management

c. External Integrations
- yt-dlp integration
- YouTube API/RSS integration
- Apprise notifications
- File system operations

##### Key Architectural Elements

**[Web Interface Layer]**

- Phoenix Controllers
- LiveView Components
- Web Templates

- v
**[Core Application Layer]**

- Media Management
- Download Workers
- Quality Management
- Retention Management

- Indexing System
- Fast Indexing (API/RSS)
- Slow Indexing (File-based)

- Profile Management
- Download Rules

- Settings & Configuration
- System Preferences

- v
**[External Services Layer]**

- yt-dlp Integration
- YouTube API/RSS
- Apprise Notifications
- File System Operations

##### Data Flow Representation

- User requests → Web Interface → Core Application
- Download requests → yt-dlp → File System
- Indexing processes → YouTube API/RSS → Database
- Notification events → Apprise servers

##### Important Subsystems to Highlight

a. Download Pipeline:
**[Source Request] → [Download Worker] → [Quality Check] → [Metadata Processing] → [File Storage]**

b. Indexing Pipeline:
**[Source Configuration] → [Fast/Slow Indexing] → [Media Discovery] → [Download Queue]**

##### Additional Elements

Supporting components:
- SQLite database connections
- Background job queues (Oban)
- File system mount points
- Configuration storage

##### Specific Implementation Details

Architectural patterns:
- Phoenix LiveView for real-time updates
- Worker pool for downloads
- File system organization
- Notification system integration

- The modular nature of the application
- Clear separation of concerns
- Integration points with external services
- Data flow through the system
- Background processing architecture

This system design should reflect Pinchflat's self-contained nature while showing its complex internal architecture that handles media downloading, processing, and management.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Web
        WI[Web Interface]
        PC[Phoenix Controllers]
        LV[LiveView Components]
        WT[Web Templates]
        
        WI --> PC
        WI --> LV
        WI --> WT
    end

    subgraph Core
        MM[Media Management]
        DM[Download Management]
        IS[Indexing Systems]
        PM[Profile Management]
        SM[Settings Management]
        MT[Metadata Management]
        SR[Source Management]
        TM[Task Management]
        LM[Lifecycle Management]
        
        subgraph IndexingSubsystem
            FI[Fast Indexing]
            SI[Slow Indexing]
            IS --> FI
            IS --> SI
        end
        
        subgraph DownloadPipeline
            DW[Download Workers]
            QM[Quality Management]
            RM[Retention Management]
            DM --> DW
            DM --> QM
            DM --> RM
        end
    end

    subgraph External
        YT[yt-dlp Integration]
        YA[YouTube API/RSS]
        AN[Apprise Notifications]
        FS[File System Operations]
    end

    %% Core Relationships
    Web --> Core
    Core --> External

    %% Data Flow
    DM --> YT
    YT --> FS
    IS --> YA
    LM --> AN

    %% Component Mappings
    click PC "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat_web/controllers/"
    click LV "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat_web/components/"
    click WT "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat_web/components/layouts/"
    click MM "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat/media/"
    click DM "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat/downloading/"
    click FI "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat/fast_indexing/"
    click SI "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat/slow_indexing/"
    click PM "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat/profiles/"
    click SM "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat/settings/"
    click YT "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat/yt_dlp/"
    click YA "https://github.com/kieraneglin/pinchflat/blob/master/lib/pinchflat/fast_indexing/youtube_api.ex"
    click AN "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat/lifecycle/notifications/"
    click FS "https://github.com/kieraneglin/pinchflat/blob/master/lib/pinchflat/utils/filesystem_utils.ex"
    click MT "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat/metadata/"
    click SR "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat/sources/"
    click TM "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat/tasks/"
    click LM "https://github.com/kieraneglin/pinchflat/tree/master/lib/pinchflat/lifecycle/"

    %% Styling
    classDef web fill:#2374ab
    classDef core fill:#57a773
    classDef external fill:#ff8c42
    classDef worker fill:#9b5de5
    classDef storage fill:#666666

    class WI,PC,LV,WT web
    class MM,DM,IS,PM,SM,MT,SR,TM,LM,FI,SI,DW,QM,RM core
    class YT,YA,AN,FS external
    class DW worker
```
