# dev-adeshina/fiel architecture

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

- Interactive diagram: https://gitdiagram.com/dev-adeshina/fiel
- Repository: https://github.com/dev-adeshina/fiel

## Overview

#### Purpose and Entry Points
A Laravel restaurant operations backend: public/customer APIs cover authentication, menus, carts, checkout, payments, and reservations; staff operate a Filament admin panel for menus, kitchen orders, inventory, tables, reporting, and analytics. HTTP enters through `public/index.php`, API route aggregates in `routes/api.php` and `routes/api/v1/*.php`, and CLI work through `artisan`.

#### Application Shape and Boundaries
Business logic is organized as bounded domains under `app/Domains`, rather than controller-centric code. Controllers validate request data, invoke domain Actions, and return API Resources. Actions coordinate Services, Repositories, Eloquent Models, and DTOs; this establishes the primary HTTP-to-domain-to-persistence boundary. Examples: `app/Http/Controllers/Order/CheckoutController.php`, `app/Domains/Order/Actions/CheckoutAction.php`, `app/Domains/Order/Repositories/OrderRepository.php`.

#### Identity and Authorization
The Auth domain owns user lifecycle: registration, login/logout, password recovery/change, email verification, account deletion, and related events/notifications. Sanctum configuration indicates token-based API authentication; permissions/roles are persisted and enforced by policies. Key paths: `app/Domains/Auth/Services/AuthService.php`, `app/Domains/Auth/Models/User.php`, `config/sanctum.php`.

#### Catalog, Cart, and Checkout
Menu management models menus, categories, items, variants, modifiers, and time/availability records. Customers add configured items to persistent carts; cart calculation precedes checkout. Checkout produces orders and order items, with status/payment-status state models and a separate inventory integration boundary. Key paths: `app/Domains/Menu/Services/MenuItemService.php`, `app/Domains/Cart/Services/CartCalculationService.php`, `app/Domains/Order/Services/OrderInventoryService.php`.

#### Payments and External Provider Boundary
Payments are provider-agnostic behind `PaymentGatewayInterface` and selected by `PaymentGatewayManager`. Supported gateway implementations include Stripe (card, Apple Pay, Google Pay), Paystack, PayPal, and Flutterwave. Initialization, verification, cancellation, refund, and provider callbacks are modeled separately; inbound webhooks are a critical trust boundary. Key paths: `app/Domains/Payment/GatewayInterfaces/PaymentGatewayInterface.php`, `app/Domains/Payment/Manages/PaymentGatewayManager.php`, `app/Domains/Payment/Webhooks/StripeWebhookHandler.php`.

#### Restaurant Operations
Inventory records items and movements, with explicit stock-adjustment actions and analytics. Reservations allocate restaurant tables, detect conflicts, and transition statuses; scheduled expiry processing runs from a console command. Kitchen-facing order endpoints/pages support operational status flow. Key paths: `app/Domains/Inventory/Actions/AdjustInventoryStockAction.php`, `app/Domains/Reservation/Services/TableAssignmentService.php`, `app/Console/Commands/ProcessReservationExpiry.php`.

#### Administration, Data, and Runtime
Filament is the staff UI and directly exposes domain-backed resources plus dashboards for kitchen, sales, inventory, and reservation analytics. Relational persistence is managed through Laravel migrations for users, catalog, carts, orders, payments, inventory, and reservations. Runtime infrastructure is Laravel/PHP with database, cache, queue, mail, filesystem, and payment/service settings configurable under `config/`; Vite supplies frontend assets. Key paths: `app/Providers/Filament/AdminPanelProvider.php`, `app/Filament/Pages/KitchenDashboard.php`, `database/migrations/2026_05_14_233653_create_orders_table.php`.

Main entry points: [`app/Domains/Order/Actions/CheckoutAction.php`](https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Order/Actions/CheckoutAction.php) (Checkout action), [`app/Providers/Filament/AdminPanelProvider.php`](https://github.com/dev-adeshina/fiel/blob/main/app/Providers/Filament/AdminPanelProvider.php) (Filament admin panel), [`app/Domains/Order/Repositories/OrderRepository.php`](https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Order/Repositories/OrderRepository.php) (Order repository), [`app/Domains/Payment/Manages/PaymentGatewayManager.php`](https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Payment/Manages/PaymentGatewayManager.php) (Payment gateway manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & Interfaces"]
  node_http["Laravel HTTP entry<br/>PHP runtime<br/>[index.php]"]
  node_api_routes["Customer API routes<br/>route aggregate<br/>[api.php]"]
  node_api_v1_routes["Versioned API routes<br/>route modules"]
  node_checkout_controller["Checkout controller<br/>HTTP controller"]
end

subgraph group_domains["Domain Layer"]
  node_auth["Auth domain<br/>identity service<br/>[AuthService.php]"]
  node_menu["Menu domain<br/>catalog service"]
  node_cart["Cart calculation<br/>cart service"]
  node_checkout_action["Checkout action<br/>order action<br/>[CheckoutAction.php]"]
  node_orders["Order repository<br/>order persistence"]
  node_inventory_integration["Order inventory service<br/>inventory boundary"]
end

subgraph group_payments["Payments"]
  node_gateway_manager{{"Payment gateway manager<br/>gateway selector"}}
  node_gateway_contract["Payment gateway contract<br/>interface"]
  node_stripe_webhook{{"Stripe webhook handler<br/>inbound webhook"}}
end

subgraph group_operations["Staff Operations"]
  node_filament["Filament admin panel<br/>staff UI"]
  node_kitchen_dashboard["Kitchen dashboard<br/>staff dashboard"]
  node_inventory["Inventory adjustment<br/>inventory action"]
  node_table_assignment["Table assignment<br/>reservation service"]
  node_reservation_expiry["Reservation expiry command<br/>scheduled CLI command"]
end

subgraph group_data["Persistence &amp; Runtime"]
  node_database[("Relational database<br/>Laravel migrations")]
  node_sanctum["Sanctum tokens<br/>API authentication<br/>[sanctum.php]"]
end

node_http -->|"dispatches"| node_api_routes
node_api_routes -->|"aggregates"| node_api_v1_routes
node_api_v1_routes -->|"routes checkout"| node_checkout_controller
node_checkout_controller -->|"invokes"| node_checkout_action
node_auth -->|"uses"| node_sanctum
node_menu -->|"configured items"| node_cart
node_cart -->|"priced cart"| node_checkout_action
node_checkout_action -->|"creates order"| node_orders
node_checkout_action -->|"initiates payment"| node_gateway_manager
node_checkout_action -->|"updates stock"| node_inventory_integration
node_gateway_manager -->|"implements contract"| node_gateway_contract
node_stripe_webhook -->|"verifies callback"| node_gateway_manager
node_orders -->|"persists"| node_database
node_inventory_integration -->|"adjusts stock"| node_inventory
node_inventory -->|"records movements"| node_database
node_table_assignment -->|"reads tables and reservations"| node_database
node_reservation_expiry -->|"expires reservations"| node_table_assignment
node_filament -->|"hosts"| node_kitchen_dashboard
node_filament -->|"manages catalog"| node_menu
node_filament -->|"manages inventory"| node_inventory
node_filament -->|"manages reservations"| node_table_assignment
node_kitchen_dashboard -->|"operates order status"| node_orders

click node_http "https://github.com/dev-adeshina/fiel/blob/main/public/index.php"
click node_api_routes "https://github.com/dev-adeshina/fiel/blob/main/routes/api.php"
click node_checkout_controller "https://github.com/dev-adeshina/fiel/blob/main/app/Http/Controllers/Order/CheckoutController.php"
click node_auth "https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Auth/Services/AuthService.php"
click node_menu "https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Menu/Services/MenuItemService.php"
click node_cart "https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Cart/Services/CartCalculationService.php"
click node_checkout_action "https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Order/Actions/CheckoutAction.php"
click node_orders "https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Order/Repositories/OrderRepository.php"
click node_inventory_integration "https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Order/Services/OrderInventoryService.php"
click node_gateway_manager "https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Payment/Manages/PaymentGatewayManager.php"
click node_gateway_contract "https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Payment/GatewayInterfaces/PaymentGatewayInterface.php"
click node_stripe_webhook "https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Payment/Webhooks/StripeWebhookHandler.php"
click node_filament "https://github.com/dev-adeshina/fiel/blob/main/app/Providers/Filament/AdminPanelProvider.php"
click node_kitchen_dashboard "https://github.com/dev-adeshina/fiel/blob/main/app/Filament/Pages/KitchenDashboard.php"
click node_inventory "https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Inventory/Actions/AdjustInventoryStockAction.php"
click node_table_assignment "https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Reservation/Services/TableAssignmentService.php"
click node_reservation_expiry "https://github.com/dev-adeshina/fiel/blob/main/app/Console/Commands/ProcessReservationExpiry.php"
click node_database "https://github.com/dev-adeshina/fiel/blob/main/database/migrations/2026_05_14_233653_create_orders_table.php"
click node_sanctum "https://github.com/dev-adeshina/fiel/blob/main/config/sanctum.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_http,node_api_routes,node_api_v1_routes,node_checkout_controller toneBlue
class node_auth,node_menu,node_cart,node_checkout_action,node_orders,node_inventory_integration toneAmber
class node_gateway_manager,node_gateway_contract,node_stripe_webhook toneMint
class node_filament,node_kitchen_dashboard,node_inventory,node_table_assignment,node_reservation_expiry toneRose
class node_database,node_sanctum toneIndigo
```

## Components

### Entry & Interfaces

- [Laravel HTTP entry](https://github.com/dev-adeshina/fiel/blob/main/public/index.php): PHP runtime · `public/index.php`
- [Customer API routes](https://github.com/dev-adeshina/fiel/blob/main/routes/api.php): route aggregate · `routes/api.php`
- **Versioned API routes**: route modules
- [Checkout controller](https://github.com/dev-adeshina/fiel/blob/main/app/Http/Controllers/Order/CheckoutController.php): HTTP controller · Validates checkout requests and returns API resources. · `app/Http/Controllers/Order/CheckoutController.php`

### Domain Layer

Actions and services coordinate restaurant workflows.

- [Auth domain](https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Auth/Services/AuthService.php): identity service · Owns account lifecycle and token-authenticated access. · `app/Domains/Auth/Services/AuthService.php`
- [Menu domain](https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Menu/Services/MenuItemService.php): catalog service · Manages menus, items, variants, modifiers, and availability. · `app/Domains/Menu/Services/MenuItemService.php`
- [Cart calculation](https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Cart/Services/CartCalculationService.php): cart service · Calculates persistent configured carts before checkout. · `app/Domains/Cart/Services/CartCalculationService.php`
- [Checkout action](https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Order/Actions/CheckoutAction.php): order action · Coordinates order creation, payment, and stock integration. · `app/Domains/Order/Actions/CheckoutAction.php`
- [Order repository](https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Order/Repositories/OrderRepository.php): order persistence · `app/Domains/Order/Repositories/OrderRepository.php`
- [Order inventory service](https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Order/Services/OrderInventoryService.php): inventory boundary · `app/Domains/Order/Services/OrderInventoryService.php`

### Payments

Provider-agnostic payment boundary.

- [Payment gateway manager](https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Payment/Manages/PaymentGatewayManager.php): gateway selector · Selects a provider implementation through a common contract. · `app/Domains/Payment/Manages/PaymentGatewayManager.php`
- [Payment gateway contract](https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Payment/GatewayInterfaces/PaymentGatewayInterface.php): interface · Defines initialization, verification, cancellation, and refund operations. · `app/Domains/Payment/GatewayInterfaces/PaymentGatewayInterface.php`
- [Stripe webhook handler](https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Payment/Webhooks/StripeWebhookHandler.php): inbound webhook · Trust boundary for provider callbacks. · `app/Domains/Payment/Webhooks/StripeWebhookHandler.php`

### Staff Operations

- [Filament admin panel](https://github.com/dev-adeshina/fiel/blob/main/app/Providers/Filament/AdminPanelProvider.php): staff UI · Exposes domain-backed management resources and dashboards. · `app/Providers/Filament/AdminPanelProvider.php`
- [Kitchen dashboard](https://github.com/dev-adeshina/fiel/blob/main/app/Filament/Pages/KitchenDashboard.php): staff dashboard · Supports kitchen order operations. · `app/Filament/Pages/KitchenDashboard.php`
- [Inventory adjustment](https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Inventory/Actions/AdjustInventoryStockAction.php): inventory action · Records stock adjustments and movements. · `app/Domains/Inventory/Actions/AdjustInventoryStockAction.php`
- [Table assignment](https://github.com/dev-adeshina/fiel/blob/main/app/Domains/Reservation/Services/TableAssignmentService.php): reservation service · Allocates tables and detects reservation conflicts. · `app/Domains/Reservation/Services/TableAssignmentService.php`
- [Reservation expiry command](https://github.com/dev-adeshina/fiel/blob/main/app/Console/Commands/ProcessReservationExpiry.php): scheduled CLI command · `app/Console/Commands/ProcessReservationExpiry.php`

### Persistence & Runtime

- [Relational database](https://github.com/dev-adeshina/fiel/blob/main/database/migrations/2026_05_14_233653_create_orders_table.php): Laravel migrations · Stores users, catalog, carts, orders, payments, inventory, and reservations. · `database/migrations/2026_05_14_233653_create_orders_table.php`
- [Sanctum tokens](https://github.com/dev-adeshina/fiel/blob/main/config/sanctum.php): API authentication · `config/sanctum.php`

## Connections

- Laravel HTTP entry → Customer API routes: dispatches
- Customer API routes → Versioned API routes: aggregates
- Versioned API routes → Checkout controller: routes checkout
- Checkout controller → Checkout action: invokes
- Auth domain → Sanctum tokens: uses
- Menu domain → Cart calculation: configured items
- Cart calculation → Checkout action: priced cart
- Checkout action → Order repository: creates order
- Checkout action → Payment gateway manager: initiates payment
- Checkout action → Order inventory service: updates stock
- Payment gateway manager → Payment gateway contract: implements contract
- Stripe webhook handler → Payment gateway manager: verifies callback
- Order repository → Relational database: persists
- Order inventory service → Inventory adjustment: adjusts stock
- Inventory adjustment → Relational database: records movements
- Table assignment → Relational database: reads tables and reservations
- Reservation expiry command → Table assignment: expires reservations
- Filament admin panel → Kitchen dashboard: hosts
- Filament admin panel → Menu domain: manages catalog
- Filament admin panel → Inventory adjustment: manages inventory
- Filament admin panel → Table assignment: manages reservations
- Kitchen dashboard → Order repository: operates order status