# spatie/laravel-medialibrary architecture

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

- Interactive diagram: https://gitdiagram.com/spatie/laravel-medialibrary
- Repository: https://github.com/spatie/laravel-medialibrary

## Overview

##### Core Components (Main Layer)

a. Media Management Layer
- It to the following sub-components:
- FileAdder System
- MediaCollection Manager
- Conversion Handler
- ResponsiveImage Generator

b. Storage Layer
- Multiple storage systems (represented as parallel components):
- Local Storage
- S3 Storage
- Custom Storage Adapters

##### Supporting Services (Secondary Layer)

a. Path Generation System
- DefaultPathGenerator
- CustomPathGenerator
- Connection to storage systems

b. URL Generation System
- DefaultUrlGenerator
- Custom URL Generators
- To the Media Management Layer

c. File Management Services
- FileNamer Service
- FileRemover Service
- Downloader Service
- To both Storage and Media Management layers

##### Processing Components

a. Conversion System
- Image Conversion Pipeline
- Custom Conversions
- Manipulation Queue
- To the following generators:
- Image Generator
- PDF Generator
- Video Generator
- SVG Generator
- AVIF Generator
- WebP Generator

b. Responsive Images System
- ResponsiveImageGenerator
- WidthCalculator
- TinyPlaceholderGenerator
- To the Conversion System

##### Integration Layer

a. Laravel Integration
- Eloquent Model Integration
- Relationship with HasMedia trait
- Migration/Database Connection
- To the Media Management Layer

b. Event System
- Media Events
- Conversion Events
- ResponsiveImage Events

##### Specific notations
- Use double lines for primary data flows
- Arrowheads to show direction of data/control flow

##### Important notes
- Async processes (like conversions)
- Points of extensibility
- Configuration injection points

##### Technical Details
- Database table relationship with media table
- File system abstraction layer
- Queue integration points
- Cache interaction points

- The modular nature of the system
- The separation of concerns between different components
- The extensibility points for custom implementations
- The flow of media files through the system
- The integration with Laravel's ecosystem

Keep the abstraction level high enough to be understandable but detailed enough to show the sophisticated architecture of the media handling system. Focus on showing how the different components interact to handle media uploads, conversions, and delivery while maintaining flexibility for different storage solutions and custom implementations.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Main
        ML[MediaLibrary]:::core
        click ML "https://github.com/spatie/laravel-medialibrary/blob/main/src/MediaLibraryServiceProvider.php"
        
        subgraph MediaManagement
            FA[FileAdder]:::core
            click FA "https://github.com/spatie/laravel-medialibrary/blob/main/src/MediaCollections/FileAdder.php"
            MCM[MediaCollection Manager]:::core
            click MCM "https://github.com/spatie/laravel-medialibrary/blob/main/src/MediaCollections/MediaCollection.php"
            MR[Media Repository]:::core
            click MR "https://github.com/spatie/laravel-medialibrary/blob/main/src/MediaCollections/MediaRepository.php"
        end
        
        subgraph Storage
            FS[Base Storage]:::storage
            click FS "https://github.com/spatie/laravel-medialibrary/blob/main/src/MediaCollections/Filesystem.php"
            S3[S3 Storage]:::storage
            click S3 "https://github.com/spatie/laravel-medialibrary/blob/main/tests/Feature/S3Integration/S3IntegrationTest.php"
            CS[Custom Storage]:::storage
        end
    end
    
    subgraph PathGeneration
        DPG[Default Path Generator]:::support
        click DPG "https://github.com/spatie/laravel-medialibrary/blob/main/src/Support/PathGenerator/DefaultPathGenerator.php"
        PGI[Path Generator Interface]:::support
        click PGI "https://github.com/spatie/laravel-medialibrary/blob/main/src/Support/PathGenerator/PathGenerator.php"
        PGF[Path Generator Factory]:::support
        click PGF "https://github.com/spatie/laravel-medialibrary/blob/main/src/Support/PathGenerator/PathGeneratorFactory.php"
    end
    
    subgraph URLGeneration
        DUG[Default URL Generator]:::support
        click DUG "https://github.com/spatie/laravel-medialibrary/blob/main/src/Support/UrlGenerator/DefaultUrlGenerator.php"
        BUG[Base URL Generator]:::support
        click BUG "https://github.com/spatie/laravel-medialibrary/blob/main/src/Support/UrlGenerator/BaseUrlGenerator.php"
        UGF[URL Generator Factory]:::support
        click UGF "https://github.com/spatie/laravel-medialibrary/blob/main/src/Support/UrlGenerator/UrlGeneratorFactory.php"
    end
    
    subgraph FileManagement
        FN[File Namer]:::support
        click FN "https://github.com/spatie/laravel-medialibrary/blob/main/src/Support/FileNamer/DefaultFileNamer.php"
        FR[File Remover]:::support
        click FR "https://github.com/spatie/laravel-medialibrary/blob/main/src/Support/FileRemover/DefaultFileRemover.php"
        DL[Downloader]:::support
        click DL "https://github.com/spatie/laravel-medialibrary/blob/main/src/Downloaders/DefaultDownloader.php"
    end
    
    subgraph Conversion
        CH[Conversion Handler]:::processing
        click CH "https://github.com/spatie/laravel-medialibrary/blob/main/src/Conversions/FileManipulator.php"
        
        subgraph Generators
            IG[Image Generator]:::processing
            click IG "https://github.com/spatie/laravel-medialibrary/blob/main/src/Conversions/ImageGenerators/Image.php"
            PDFG[PDF Generator]:::processing
            click PDFG "https://github.com/spatie/laravel-medialibrary/blob/main/src/Conversions/ImageGenerators/Pdf.php"
            VG[Video Generator]:::processing
            click VG "https://github.com/spatie/laravel-medialibrary/blob/main/src/Conversions/ImageGenerators/Video.php"
            SVGG[SVG Generator]:::processing
            click SVGG "https://github.com/spatie/laravel-medialibrary/blob/main/src/Conversions/ImageGenerators/Svg.php"
            AVIFG[AVIF Generator]:::processing
            click AVIFG "https://github.com/spatie/laravel-medialibrary/blob/main/src/Conversions/ImageGenerators/Avif.php"
            WEBPG[WebP Generator]:::processing
            click WEBPG "https://github.com/spatie/laravel-medialibrary/blob/main/src/Conversions/ImageGenerators/Webp.php"
        end
    end
    
    subgraph ResponsiveImages
        RIG[Responsive Image Generator]:::processing
        click RIG "https://github.com/spatie/laravel-medialibrary/blob/main/src/ResponsiveImages/ResponsiveImageGenerator.php"
        WC[Width Calculator]:::processing
        click WC "https://github.com/spatie/laravel-medialibrary/blob/main/src/ResponsiveImages/WidthCalculator/WidthCalculator.php"
        TPG[Tiny Placeholder Generator]:::processing
        click TPG "https://github.com/spatie/laravel-medialibrary/blob/main/src/ResponsiveImages/TinyPlaceholderGenerator/TinyPlaceholderGenerator.php"
    end
    
    subgraph Integration
        EI[Eloquent Integration]:::integration
        click EI "https://github.com/spatie/laravel-medialibrary/blob/main/src/HasMedia.php"
        MI[Model Integration]:::integration
        click MI "https://github.com/spatie/laravel-medialibrary/blob/main/src/InteractsWithMedia.php"
        DB[Database Migration]:::integration
        click DB "https://github.com/spatie/laravel-medialibrary/blob/main/database/migrations/create_media_table.php.stub"
    end
    
    %% Connections
    ML --> MediaManagement
    ML --> Storage
    ML --> Conversion
    ML --> ResponsiveImages
    
    FA --> Storage
    MCM --> Storage
    MR --> Storage
    
    Storage --> PathGeneration
    Storage --> URLGeneration
    Storage --> FileManagement
    
    Conversion --> Generators
    Conversion --> ResponsiveImages
    
    Integration --> ML
    
    %% Styles
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef storage fill:#4CAF50,stroke:#2E7D32,color:white
    classDef support fill:#9E9E9E,stroke:#616161,color:white
    classDef processing fill:#FF9800,stroke:#EF6C00,color:white
    classDef integration fill:#9C27B0,stroke:#6A1B9A,color:white
    
    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[Storage Systems]:::storage
        L3[Supporting Services]:::support
        L4[Processing Components]:::processing
        L5[Integration Components]:::integration
    end
```
