# shopperlabs/shopper architecture

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

- Interactive diagram: https://gitdiagram.com/shopperlabs/shopper
- Repository: https://github.com/shopperlabs/shopper

## Overview

##### Project type and purpose
- This is a Laravel-based, headless e-commerce admin panel framework (“Shopper Framework”) distributed as a monorepo.
- It exposes an admin UI (Blade + Livewire), core domain logic (Eloquent models, repositories, events), and a sidebar component as separate Composer packages.

##### File structure
- Top-level “packages” directory with three Composer packages:
- packages/admin – the admin UI (controllers, Livewire components, assets, views, routes)
- packages/core – the domain layer (models, migrations, repositories, events, console commands)
- packages/sidebar – a sidebar/menu builder library used by the admin UI
- Root has build tooling (package.json & pnpm scripts for JS/CSS assets, monorepo-builder.php), CI workflows (.github/workflows), and standard Laravel config (artisan, composer.json, phpunit.xml).

##### README insights
- Shopper Framework is for managing catalog, orders, discounts, customers, reviews, currencies, zones.
- Built on Laravel 11.x, uses Tailwind, Livewire, FilamentPHP, Wire Elements.
- Encourages extensibility (config files, stubs, contracts).

##### Main components and relationships
a. Frontend (Admin UI)
- Browser clients interact via HTTP(S), sending requests to Laravel routes defined in packages/admin/routes/*.php
- UI layer comprised of Blade templates, Livewire components (server-driven), and bundled JS/CSS assets (pnpm build outputs shopper.js/shopper.css)
- Sidebar builder (packages/sidebar) renders navigation dynamically via middleware ResolveSidebars and Blade view composers
b. Backend (Laravel app)
- HTTP Kernel and middleware stack (packages/admin/src/Http/Middleware + core middleware)
- Controllers (AssetController, Auth controllers) and Livewire endpoints dispatch actions
- Actions & Jobs (packages/admin/src/Actions + Jobs) implement business workflows (e.g., CreateProductAction, AttachDiscountToCustomers job)
c. Domain & Data (Core Package)
- Eloquent Models (packages/core/src/Models) represent Customers, Orders, Products, etc.
- Migrations & Seeders under packages/core/database set up schema & initial data
- Repositories & Contracts implement data access and domain logic (packages/core/src/Repositories + Contracts)
- Events & Listeners propagate domain events (OrderCreated → listeners, attached via Laravel’s event system)
d. Infrastructure services
- Database (MySQL/PostgreSQL): stores domain data
- Cache / Queue (Redis): optional for event-driven jobs (discount attachments, notifications)
- Mail (SMTP / third-party): sending credentials, order notifications
- File storage (local/S3): product images, user avatars

##### Architectural patterns & design principles
- Monorepo modularization: clear separation of UI (admin), domain (core), and cross-cutting library (sidebar)
- MVC + Livewire (server-driven components)
- Action classes (Single Responsibility) for core use cases
- Repository pattern encapsulating data access
- Event-driven architecture for side effects (Jobs and Listeners)
- Contract-based extensibility (interfaces under src/Contracts)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        Browser["Browser (Web Client)"]:::external
    end

    %% HTTP Layer
    subgraph "HTTP Layer"
        Kernel["Laravel HTTP Kernel"]:::internal
        Routes["Admin Routes"]:::internal
        Middleware["Admin Middleware"]:::internal
        SidebarMW["ResolveSidebars Middleware"]:::internal
    end

    %% Application Layer
    subgraph "Application Layer"
        Controllers["Admin Controllers"]:::internal
        Livewire["Livewire Components"]:::internal
        Actions["Admin Actions"]:::internal
        Jobs["Admin Jobs"]:::internal
        Views["Blade Views & Templates"]:::internal
        SidebarPkg["Sidebar Library"]:::internal
        SidebarPres["Sidebar Renderers"]:::internal
        SidebarSP["Sidebar ServiceProvider"]:::internal
    end

    %% Domain Layer
    subgraph "Domain Layer"
        CorePkg["Core Domain Package"]:::internal
        Models["Core Models"]:::internal
        Repos["Repositories & Contracts"]:::internal
        Events["Core Events"]:::internal
        Migrations["Migrations & Seeders"]:::internal
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        DB["Database"]:::storage
        Redis["Cache / Queue (Redis)"]:::storage
        Mail["Mail Service"]:::external
        Storage["File Storage"]:::external
    end

    %% Flows
    Browser -->|"/admin/*"| Kernel
    Kernel -->|routes| Routes
    Kernel -->|middleware| Middleware
    Kernel -->|sidebar mw| SidebarMW
    SidebarMW --> SidebarPres
    SidebarPres --> Views

    Routes --> Controllers
    Middleware --> Livewire

    Controllers --> Actions
    Livewire --> Actions
    Controllers --> Views

    Actions --> Repos
    Repos --> Models
    Repos --> DB

    Actions --> Jobs
    Jobs --> Redis
    Redis --> Repos

    Controllers -->|send mail| Mail

    Models --> Migrations
    Migrations --> DB

    Kernel --> SidebarSP

    %% Click Events
    click SidebarSP "https://github.com/shopperlabs/shopper/blob/2.x/packages/sidebar/src/SidebarServiceProvider.php"
    click SidebarMW "https://github.com/shopperlabs/shopper/blob/2.x/packages/sidebar/src/Middleware/ResolveSidebars.php"
    click SidebarPres "https://github.com/shopperlabs/shopper/tree/2.x/packages/sidebar/src/Presentation"
    click SidebarPkg "https://github.com/shopperlabs/shopper/tree/2.x/packages/sidebar"
    click Models "https://github.com/shopperlabs/shopper/tree/2.x/packages/core/src/Models"
    click Repos "https://github.com/shopperlabs/shopper/tree/2.x/packages/core/src/Repositories"
    click Repos "https://github.com/shopperlabs/shopper/tree/2.x/packages/core/src/Contracts"
    click Events "https://github.com/shopperlabs/shopper/tree/2.x/packages/core/src/Events"
    click Migrations "https://github.com/shopperlabs/shopper/tree/2.x/packages/core/database/migrations"
    click Migrations "https://github.com/shopperlabs/shopper/tree/2.x/packages/core/database/seeders"
    click CorePkg "https://github.com/shopperlabs/shopper/tree/2.x/packages/core"
    click Views "https://github.com/shopperlabs/shopper/tree/2.x/packages/admin/resources/views"
    click Jobs "https://github.com/shopperlabs/shopper/tree/2.x/packages/admin/src/Jobs"
    click Actions "https://github.com/shopperlabs/shopper/tree/2.x/packages/admin/src/Actions"
    click Livewire "https://github.com/shopperlabs/shopper/tree/2.x/packages/admin/src/Livewire"
    click Controllers "https://github.com/shopperlabs/shopper/tree/2.x/packages/admin/src/Http/Controllers"
    click Middleware "https://github.com/shopperlabs/shopper/tree/2.x/packages/admin/src/Http/Middleware"
    click Routes "https://github.com/shopperlabs/shopper/tree/2.x/packages/admin/routes"
    click SidebarPres "https://github.com/shopperlabs/shopper/tree/2.x/packages/sidebar/src/Presentation"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#3498DB,stroke-width:1px
    classDef storage fill:#D5F5E3,stroke:#27AE60,stroke-width:1px
    classDef external fill:#E5E7E9,stroke:#7F8C8D,stroke-width:1px
```
