# awcodes/filament-curator architecture

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

- Interactive diagram: https://gitdiagram.com/awcodes/filament-curator
- Repository: https://github.com/awcodes/filament-curator

## Overview

##### Project Type and Purpose
- Type: A Laravel “plugin” package (PHP library) that integrates into Filament Admin panels or stand-alone Filament Forms to provide a media picker/manager.
- Purpose: Let developers embed a modal/UI for selecting, uploading, curating, and serving images via Glide (on-the-fly image manipulation).

##### File Structure
- Top-level:
– src/ → core PHP code (ServiceProvider, Controllers, Models, Actions, Components, Concerns, Observers, PathGenerators, Glide integration, Curations).
– resources/ → Blade views (modals, components), JavaScript/CSS builds, translation files.
– config/curator.php → global settings.
– database/migrations & factories → media table schema.
– bin/build.js, package.json, tailwind.config.js, postcss.config.cjs → front-end asset build pipeline.
– routes/web.php → Glide/image-serving route.
- Patterns:
– MVC (MediaController, Media model, Blade views).
– Service provider pattern (CuratorServiceProvider).
– Observer pattern (MediaObserver).
– Strategy pattern for path generation (PathGenerator interface) and for Glide server (ServerFactory).

##### Key Insights from README
- Installs via Composer; registers artisan commands (curator:install, curator:upgrade).
- Requires a custom Filament theme + Cropper.js → CSS/JS assets loaded into Filament.
- Exposes Blade components: <x-curator-picker>, <x-curator-glider>, <x-curator-curation>.
- Uses league/glide for dynamic image URLs and presets for curation.

##### Main Components & Their Relationships

A. Host Laravel Application (outermost context)
- ServiceProvider Registration → loads config, publishes assets, migrations, registers Glide route & Filament plugin.
- Artisan Commands → build assets, run migrations.

B. Filament Admin / Filament Forms UI
- Blade views & Components (resources/views, src/View/Components)
- CuratorPicker field (JS/Cropper.js + plugin.css)
- Modals (upload & curation UI)

→ HTTP requests (AJAX/form submits) → MediaController

C. Backend Processing
- src/Http/Controllers/MediaController.php (handles uploads, CRUD)
- src/Actions (MediaAction, MultiUploadAction) – encapsulate upload logic
- src/Models/Media.php – Eloquent model mapped to media table
- src/Observers/MediaObserver.php – hooks on model events (e.g., generate thumbnails, remove files)
- src/PathGenerators – determine storage paths
- Storage Disk (Laravel Filesystem) – writes files to disk/cloud

D. Image Serving & Curation
- routes/web.php → Glide route (e.g., /curator)
- src/Glide/GlideBuilder & DefaultServerFactory – configure and return League\Glide Server
- Glide pipeline → reads source image, applies query parameters (resize, crop, filters), outputs response
- Glider Blade component → generates signed Glide URLs, optionally srcset/fallback

E. Persistence
- Database (media table + potential pivot tables for morph/many relationships)
- Migrations (database/migrations)

F. Front-end Build Tooling
- bin/build.js, package.json, tailwind.config.js, postcss.config.cjs
- Outputs plugin.css, curator.js, curation.js in resources/dist

##### Architectural Patterns & Design Principles
- Modular design: clear separation between UI (Blade/JS/CSS), domain logic (Actions, Models), and infrastructure (Storage, Glide).
- Dependency Injection: ServiceProvider binds interfaces (ServerFactory, PathGenerator).
- Open/Closed: PathGenerators and GliderFallbacks are pluggable by implementing provided interfaces.
- Observer: Post-upload hooks for additional processing.

##### Technologies & Frameworks (label these
- PHP 8+, Laravel Framework, Filament Admin package
- Composer for PHP dependencies
- Blade components, Eloquent ORM, Laravel Filesystem
- League\Glide for image processing
- Cropper.js, Tailwind CSS, PostCSS for front-end
- Pest/PhpUnit for tests

– UI (blue): Blade views, JS/CSS, Cropper.js
– Backend Logic (green): Controllers, Actions, Observers, ServiceProvider
– Data (orange): Eloquent Models, Migrations, Database, Storage Disk
– External/3rd-party (gray): Filament Admin, League\Glide, Laravel Framework

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Application Boundary
    subgraph "Host Laravel Application" 
        direction TB
        SP["CuratorServiceProvider"]:::backend
        PP["CuratorPlugin"]:::backend
        CFG["config/curator.php"]:::backend
        AC["Artisan Commands"]:::backend
    end

    %% UI Layer
    subgraph "UI Layer (Blade / JS / CSS)" 
        direction TB
        BC["Blade Components & Templates"]:::ui
        JS["JavaScript (Cropper.js, curator.js, curation.js)"]:::ui
        CSS["Styles (plugin.css)"]:::ui
        Picker["<x-curator-picker> Field"]:::ui
    end

    %% Backend Logic
    subgraph "Backend Logic" 
        direction TB
        MC["MediaController"]:::backend
        MA["MediaAction"]:::backend
        MU["MultiUploadAction"]:::backend
        MO["MediaObserver"]:::backend
        subgraph "PathGenerators" 
            direction TB
            PGI["PathGenerator Interface"]:::backend
            DPG["DefaultPathGenerator"]:::backend
            DaPG["DatePathGenerator"]:::backend
            UP{"UserPathGenerator"}:::backend
        end
        subgraph "Glide Integration"
            direction TB
            GB["GlideBuilder"]:::backend
            SFI["ServerFactory Interface"]:::backend
            DSF["DefaultServerFactory"]:::backend
            GF["GliderFallback"]:::backend
        end
        ROUTE["routes/web.php (Glide route)"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        MM["Media Model"]:::data
        MF["MediaFactory"]:::data
        MIG["Migrations"]:::data
        DB["Database (media table)"]:::data
        SD["Storage Disk"]:::data
    end

    %% External Dependencies
    subgraph "External / Third-party" 
        direction TB
        FIL["Filament Admin"]:::external
        LAR["Laravel Framework"]:::external
        GLIDE["League\\Glide"]:::external
    end

    %% Connections
    FIL -->|integrates| BC
    LAR -->|bootstraps| SP
    SP -->|publishes config/views/migrations| CFG
    SP -->|registers routes| ROUTE
    SP -->|binds interfaces| PGI
    SP -->|binds interfaces| SFI
    AC -->|runs migrations| MIG
    AC -->|builds assets| JS
    Picker -->|AJAX/form submits| MC
    JS -->|uploads| MC
    MC -->|uses| MA
    MC -->|uses| MU
    MC -->|dispatches| MO
    MA -->|stores files| SD
    MU -->|stores files| SD
    MO -->|generates thumbnails| SD
    PGI -->|implemented by| DPG
    PGI -->|implemented by| DaPG
    PGI -->|implemented by| UP
    ROUTE -->|invokes| DSF
    DSF -->|builds server via| GB
    GB -->|processes images| GLIDE
    GF -->|fallback| SD
    MC -->|persists metadata| MM
    MM -->|factory| MF
    MM -->|table schema| MIG
    MM -->|records in| DB
    BC -->|renders| Picker
    CSS -->|styles| Picker

    %% Click events
    click SP "https://github.com/awcodes/filament-curator/blob/3.x/src/CuratorServiceProvider.php"
    click PP "https://github.com/awcodes/filament-curator/blob/3.x/src/CuratorPlugin.php"
    click CFG "https://github.com/awcodes/filament-curator/blob/3.x/config/curator.php"
    click MIG "https://github.com/awcodes/filament-curator/blob/3.x/database/migrations/create_media_table.php.stub"
    click MIG "https://github.com/awcodes/filament-curator/blob/3.x/database/migrations/add_tenant_aware_column_to_media_table.php.stub"
    click MIG "https://github.com/awcodes/filament-curator/blob/3.x/database/migrations/upgrade_media_table.php.stub"
    click MM "https://github.com/awcodes/filament-curator/blob/3.x/src/Models/Media.php"
    click MF "https://github.com/awcodes/filament-curator/blob/3.x/database/factories/MediaFactory.php"
    click MC "https://github.com/awcodes/filament-curator/blob/3.x/src/Http/Controllers/MediaController.php"
    click MA "https://github.com/awcodes/filament-curator/blob/3.x/src/Actions/MediaAction.php"
    click MU "https://github.com/awcodes/filament-curator/blob/3.x/src/Actions/MultiUploadAction.php"
    click MO "https://github.com/awcodes/filament-curator/blob/3.x/src/Observers/MediaObserver.php"
    click PGI "https://github.com/awcodes/filament-curator/blob/3.x/src/PathGenerators/Contracts/PathGenerator.php"
    click DPG "https://github.com/awcodes/filament-curator/blob/3.x/src/PathGenerators/DefaultPathGenerator.php"
    click DaPG "https://github.com/awcodes/filament-curator/blob/3.x/src/PathGenerators/DatePathGenerator.php"
    click UP "https://github.com/awcodes/filament-curator/blob/3.x/src/PathGenerators/UserPathGenerator.php"
    click GB "https://github.com/awcodes/filament-curator/blob/3.x/src/Glide/GlideBuilder.php"
    click SFI "https://github.com/awcodes/filament-curator/blob/3.x/src/Glide/Contracts/ServerFactory.php"
    click DSF "https://github.com/awcodes/filament-curator/blob/3.x/src/Glide/DefaultServerFactory.php"
    click GF "https://github.com/awcodes/filament-curator/blob/3.x/src/Glide/GliderFallback.php"
    click ROUTE "https://github.com/awcodes/filament-curator/blob/3.x/routes/web.php"
    click BC "https://github.com/awcodes/filament-curator/tree/3.x/resources/views/components/"
    click Uploader "https://github.com/awcodes/filament-curator/blob/3.x/src/Components/Forms/CuratorPicker.php"
    click Uploader "https://github.com/awcodes/filament-curator/blob/3.x/src/Components/Forms/CuratorEditor.php"
    click Uploader "https://github.com/awcodes/filament-curator/blob/3.x/src/Components/Forms/Uploader.php"
    click Uploader "https://github.com/awcodes/filament-curator/blob/3.x/src/Components/Modals/CuratorPanel.php"
    click Uploader "https://github.com/awcodes/filament-curator/blob/3.x/src/Components/Modals/CuratorCuration.php"
    click Uploader "https://github.com/awcodes/filament-curator/blob/3.x/src/Components/Tables/CuratorColumn.php"
    click Uploader "https://github.com/awcodes/filament-curator/blob/3.x/src/View/Components/Glider.php"
    click Uploader "https://github.com/awcodes/filament-curator/blob/3.x/src/View/Components/Curation.php"
    click SD "https://github.com/awcodes/filament-curator/tree/3.x/storage/"
    click AC "https://github.com/awcodes/filament-curator/blob/3.x/src/Commands/UpgradeCommand.php"
    click JS "https://github.com/awcodes/filament-curator/blob/3.x/resources/js/curator.js"
    click JS "https://github.com/awcodes/filament-curator/blob/3.x/resources/js/curation.js"
    click CSS "https://github.com/awcodes/filament-curator/blob/3.x/resources/css/plugin.css"
    click JS "https://github.com/awcodes/filament-curator/blob/3.x/bin/build.js"
    click JS "https://github.com/awcodes/filament-curator/blob/3.x/package.json"
    click JS "https://github.com/awcodes/filament-curator/blob/3.x/postcss.config.cjs"
    click JS "https://github.com/awcodes/filament-curator/blob/3.x/tailwind.config.js"
    click JS "https://github.com/awcodes/filament-curator/blob/3.x/resources/dist/curator.js"
    click JS "https://github.com/awcodes/filament-curator/blob/3.x/resources/dist/curator.css"
    click JS "https://github.com/awcodes/filament-curator/blob/3.x/resources/dist/curation.js"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#E6F4EA,stroke:#28A745,color:#28A745;
    classDef data fill:#FFF1E6,stroke:#E87722,color:#E87722;
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
```
