# liberusoftware/ecommerce-laravel architecture

> Architecture diagram of the GitHub repository liberusoftware/ecommerce-laravel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/liberusoftware/ecommerce-laravel
- Repository: https://github.com/liberusoftware/ecommerce-laravel

## Overview

#### Purpose and runtime
Liberu Ecommerce is a Laravel 13/PHP 8.5 commerce platform: server-rendered storefront, Livewire interactions, Filament operations panels, REST and GraphQL interfaces. It supports catalogues, carts, checkout, orders, inventory, payments, shipping, subscriptions, analytics, and merchant tenancy. Primary bootstrap/HTTP entry points are `public/index.php`, `bootstrap/app.php`, and `artisan`.

#### Request surfaces and access boundary
Web, API, console, broadcast, and social-auth routes are separated in `routes/web.php`, `routes/api.php`, `routes/console.php`, and `routes/channels.php`. Laravel middleware establishes request security and commerce context, notably channel resolution and team permissions in `app/Http/Middleware/ResolveChannel.php` and `app/Http/Middleware/TeamsPermission.php`. Fortify/Jetstream actions and providers implement authentication, profiles, teams, and API-token-related account behavior under `app/Actions/Fortify/` and `app/Providers/FortifyServiceProvider.php`.

#### Tenant/store/channel model
The core isolation boundary is merchant team plus store/channel context. Persistent entities include `app/Models/Team.php`, `app/Models/Store.php`, `app/Models/Channel.php`, and `app/Models/ChannelDomain.php`; scoping behavior is centralized by `app/Traits/IsStoreScoped.php` and `app/Traits/IsTenantModel.php`. Incoming host/channel resolution selects the operating context before storefront and API work; policies and panel tenancy then constrain resource access.

#### Commerce transaction flow
Storefront controllers and Livewire components drive product discovery and cart interaction through `app/Http/Controllers/Frontend/ProductController.php`, `app/Livewire/ShoppingCart.php`, and `app/Services/CartService.php`. Checkout funnels through `app/Http/Controllers/CheckoutController.php` into `app/Services/CheckoutService.php`, persisting `app/Models/Order.php` and `app/Models/OrderItem.php`. This is the main consistency boundary: pricing/promotions, tax, stock, shipping, payment result, and order-state transitions must be evaluated under the resolved store/team context.

#### Payments, fulfillment, and external callbacks
Payment abstraction is defined by `app/Interfaces/PaymentGatewayInterface.php` and selected via `app/Factories/PaymentGatewayFactory.php`; concrete Stripe and PayPal implementations live in `app/Services/PaymentGateways/StripeGateway.php` and `app/Services/PaymentGateways/PayPalGateway.php`. Provider webhooks enter through `app/Http/Controllers/StripeWebhookController.php` and `app/Http/Controllers/PaypalWebhookController.php`. Shipping uses `app/Services/ShippingService.php` with carrier adapters such as `app/Services/Shipping/EasyPostCarrier.php`. Successful dropship orders are deferred to `app/Jobs/DispatchDropshippingOrder.php`, isolating supplier/DropXL calls from the checkout response.

#### Back-office, APIs, and asynchronous operations
Two Filament panels expose separate admin and merchant operational surfaces, configured by `app/Providers/Filament/AdminPanelProvider.php` and `app/Providers/Filament/AppPanelProvider.php`; resources operate over the same scoped models. REST controllers under `app/Http/Controllers/Api/` provide headless management/store functions, while GraphQL is handled by `app/Http/Controllers/GraphQLController.php` and `app/GraphQL/StorefrontSchema.php`. Queue-backed outbound webhooks use `app/Jobs/DispatchOutboundWebhook.php` and `app/Jobs/SendWebhookDelivery.php`; scheduled maintenance, reporting, recommendation, inventory, and retry work is registered in `app/Console/Kernel.php`.

#### Infrastructure and deployment
The application targets MySQL/MariaDB/PostgreSQL with schema ownership in `database/migrations/`; Redis is provisioned for cache/queues in `k8s/redis.yaml`, with Horizon and Reverb configuration in `config/horizon.php` and `config/reverb.php`. Docker supports PHP-FPM/Nginx plus supervisor workers and scheduler configuration under `.docker/`; Octane variants support RoadRunner, Swoole, and FrankenPHP under `.docker/octane/`. Kubernetes deployment, ingress, autoscaling, network policy, and MySQL stateful infrastructure are defined under `k8s/`.

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry &amp; access"]
  node_bootstrap["Laravel bootstrap<br/>PHP entry points<br/>[app.php]"]
  node_routes["Route surfaces<br/>Laravel routes<br/>[web.php]"]
  node_access["Commerce access context<br/>HTTP middleware<br/>[ResolveChannel.php]"]
  node_identity["Accounts &amp; teams<br/>Fortify actions"]
end

subgraph group_commerce["Commerce core"]
  node_tenant["Merchant store context<br/>tenant models and scopes<br/>[Team.php]"]
  node_storefront["Storefront &amp; cart<br/>controllers and Livewire<br/>[ShoppingCart.php]"]
  node_cart["Cart service<br/>commerce service<br/>[CartService.php]"]
  node_checkout["Checkout service<br/>transaction service"]
  node_orders[("Orders<br/>commerce models<br/>[Order.php]")]
end

subgraph group_operations["Operations &amp; integrations"]
  node_payments{{"Payment gateway layer<br/>gateway factory"}}
  node_payment_callbacks["Payment webhooks<br/>webhook controllers"]
  node_shipping{{"Shipping service<br/>carrier integration"}}
  node_dropship_job["Dropship dispatch<br/>queued job"]
  node_panels["Admin &amp; merchant panels<br/>Filament panels"]
  node_headless_api["REST &amp; GraphQL<br/>headless interfaces"]
  node_outbound_webhooks["Outbound webhook delivery<br/>queued jobs"]
end

subgraph group_platform["Platform runtime"]
  node_scheduler["Scheduled operations<br/>console kernel<br/>[Kernel.php]"]
  node_database[("Commerce database<br/>MySQL/MariaDB/PostgreSQL")]
  node_redis[("Redis queues &amp; cache<br/>[redis.yaml]")]
  node_workers["Queue workers &amp; realtime<br/>Horizon and Reverb<br/>[horizon.php]"]
  node_deployment["Container &amp; Kubernetes deployment<br/>Docker and Kubernetes"]
end

node_bootstrap -->|"loads"| node_routes
node_routes -->|"web/API requests"| node_access
node_access -->|"authenticates"| node_identity
node_access -->|"resolves channel and team"| node_tenant
node_tenant -->|"scopes"| node_storefront
node_storefront -->|"cart actions"| node_cart
node_cart -->|"checkout cart"| node_checkout
node_checkout -->|"persists"| node_orders
node_checkout -->|"authorizes payment"| node_payments
node_checkout -->|"rates and fulfillment"| node_shipping
node_payments -.->|"provider callbacks"| node_payment_callbacks
node_payment_callbacks -->|"updates payment state"| node_checkout
node_orders -->|"successful dropship order"| node_dropship_job
node_dropship_job -->|"queued in"| node_redis
node_panels -->|"enforces panel tenancy"| node_tenant
node_headless_api -->|"uses request context"| node_access
node_headless_api -->|"commerce operations"| node_checkout
node_outbound_webhooks -->|"queues deliveries"| node_redis
node_scheduler -->|"schedules queued work"| node_redis
node_workers -->|"consumes queues"| node_redis
node_tenant -->|"scoped persistence"| node_database
node_orders -->|"stores"| node_database
node_deployment -->|"hosts application"| node_bootstrap
node_deployment -->|"runs workers and realtime"| node_workers

click node_bootstrap "https://github.com/liberusoftware/ecommerce-laravel/blob/main/bootstrap/app.php"
click node_routes "https://github.com/liberusoftware/ecommerce-laravel/blob/main/routes/web.php"
click node_access "https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Http/Middleware/ResolveChannel.php"
click node_tenant "https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Models/Team.php"
click node_storefront "https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Livewire/ShoppingCart.php"
click node_cart "https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Services/CartService.php"
click node_checkout "https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Services/CheckoutService.php"
click node_orders "https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Models/Order.php"
click node_payments "https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Factories/PaymentGatewayFactory.php"
click node_payment_callbacks "https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Http/Controllers/StripeWebhookController.php"
click node_shipping "https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Services/ShippingService.php"
click node_dropship_job "https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Jobs/DispatchDropshippingOrder.php"
click node_panels "https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Providers/Filament/AppPanelProvider.php"
click node_headless_api "https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Http/Controllers/GraphQLController.php"
click node_outbound_webhooks "https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Jobs/DispatchOutboundWebhook.php"
click node_scheduler "https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Console/Kernel.php"
click node_redis "https://github.com/liberusoftware/ecommerce-laravel/blob/main/k8s/redis.yaml"
click node_workers "https://github.com/liberusoftware/ecommerce-laravel/blob/main/config/horizon.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bootstrap,node_routes,node_access,node_identity toneBlue
class node_tenant,node_storefront,node_cart,node_checkout,node_orders toneAmber
class node_payments,node_payment_callbacks,node_shipping,node_dropship_job,node_panels,node_headless_api,node_outbound_webhooks toneMint
class node_scheduler,node_database,node_redis,node_workers,node_deployment toneRose
```

## Components

### Entry & access

- [Laravel bootstrap](https://github.com/liberusoftware/ecommerce-laravel/blob/main/bootstrap/app.php): PHP entry points · Starts HTTP and console application runtimes. · `bootstrap/app.php`
- [Route surfaces](https://github.com/liberusoftware/ecommerce-laravel/blob/main/routes/web.php): Laravel routes · Separates web, API, console, broadcast, and social-auth entry routes. · `routes/web.php`
- [Commerce access context](https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Http/Middleware/ResolveChannel.php): HTTP middleware · Resolves channel and enforces team permissions before commerce work. · `app/Http/Middleware/ResolveChannel.php`
- **Accounts & teams**: Fortify actions · Handles authentication, profiles, teams, and API tokens.

### Commerce core

- [Merchant store context](https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Models/Team.php): tenant models and scopes · Team, store, channel, and domain isolation governs all scoped data. · `app/Models/Team.php`
- [Storefront & cart](https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Livewire/ShoppingCart.php): controllers and Livewire · Serves product discovery and interactive shopping carts. · `app/Livewire/ShoppingCart.php`
- [Cart service](https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Services/CartService.php): commerce service · `app/Services/CartService.php`
- [Checkout service](https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Services/CheckoutService.php): transaction service · Coordinates pricing, tax, stock, shipping, payment, and order state. · `app/Services/CheckoutService.php`
- [Orders](https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Models/Order.php): commerce models · Persists completed orders and line items. · `app/Models/Order.php`

### Operations & integrations

- [Payment gateway layer](https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Factories/PaymentGatewayFactory.php): gateway factory · Selects Stripe or PayPal behind a common payment interface. · `app/Factories/PaymentGatewayFactory.php`
- [Payment webhooks](https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Http/Controllers/StripeWebhookController.php): webhook controllers · Receives Stripe and PayPal provider callbacks. · `app/Http/Controllers/StripeWebhookController.php`
- [Shipping service](https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Services/ShippingService.php): carrier integration · Uses carrier adapters for fulfillment shipping operations. · `app/Services/ShippingService.php`
- [Dropship dispatch](https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Jobs/DispatchDropshippingOrder.php): queued job · Defers supplier and DropXL submission after successful orders. · `app/Jobs/DispatchDropshippingOrder.php`
- [Admin & merchant panels](https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Providers/Filament/AppPanelProvider.php): Filament panels · Separate operational surfaces over shared scoped resources. · `app/Providers/Filament/AppPanelProvider.php`
- [REST & GraphQL](https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Http/Controllers/GraphQLController.php): headless interfaces · Provides management, storefront, and GraphQL access. · `app/Http/Controllers/GraphQLController.php`
- [Outbound webhook delivery](https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Jobs/DispatchOutboundWebhook.php): queued jobs · Dispatches and delivers outbound event notifications. · `app/Jobs/DispatchOutboundWebhook.php`

### Platform runtime

- [Scheduled operations](https://github.com/liberusoftware/ecommerce-laravel/blob/main/app/Console/Kernel.php): console kernel · Runs maintenance, reporting, recommendations, inventory, and retries. · `app/Console/Kernel.php`
- **Commerce database**: MySQL/MariaDB/PostgreSQL · Schema migrations own persistent application data.
- [Redis queues & cache](https://github.com/liberusoftware/ecommerce-laravel/blob/main/k8s/redis.yaml): Redis · Provides queue and cache backing for workers. · `k8s/redis.yaml`
- [Queue workers & realtime](https://github.com/liberusoftware/ecommerce-laravel/blob/main/config/horizon.php): Horizon and Reverb · Processes queued work and supports realtime broadcasting. · `config/horizon.php`
- **Container & Kubernetes deployment**: Docker and Kubernetes · Runs PHP-FPM/Nginx, workers, scheduler, and scalable cluster infrastructure.

## Connections

- Laravel bootstrap → Route surfaces: loads
- Route surfaces → Commerce access context: web/API requests
- Commerce access context → Accounts & teams: authenticates
- Commerce access context → Merchant store context: resolves channel and team
- Merchant store context → Storefront & cart: scopes
- Storefront & cart → Cart service: cart actions
- Cart service → Checkout service: checkout cart
- Checkout service → Orders: persists
- Checkout service → Payment gateway layer: authorizes payment
- Checkout service → Shipping service: rates and fulfillment
- Payment gateway layer → Payment webhooks: provider callbacks
- Payment webhooks → Checkout service: updates payment state
- Orders → Dropship dispatch: successful dropship order
- Dropship dispatch → Redis queues & cache: queued in
- Admin & merchant panels → Merchant store context: enforces panel tenancy
- REST & GraphQL → Commerce access context: uses request context
- REST & GraphQL → Checkout service: commerce operations
- Outbound webhook delivery → Redis queues & cache: queues deliveries
- Scheduled operations → Redis queues & cache: schedules queued work
- Queue workers & realtime → Redis queues & cache: consumes queues
- Merchant store context → Commerce database: scoped persistence
- Orders → Commerce database: stores
- Container & Kubernetes deployment → Laravel bootstrap: hosts application
- Container & Kubernetes deployment → Queue workers & realtime: runs workers and realtime
