# ecarlsson-r/commercesystem-api architecture

> Architecture diagram of the GitHub repository ecarlsson-r/commercesystem-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ecarlsson-r/commercesystem-api
- Repository: https://github.com/ecarlsson-r/commercesystem-api

## Overview

CommerceSystem-API is a Laravel commerce and ERP backend. Clients enter through API routes and use storefront discovery, cart/order flows, or clerk-facing sales and inventory operations; these feed branch-scoped stock and transaction records, with reporting and event-driven notifications/KPI tracking alongside the main workflow. AI assistance and recommendations are a separate capability. Several subsystems are represented from the README and file tree where source was not sampled; their internal call details are therefore not inferred.

Main entry points: [`routes/api.php`](https://github.com/ecarlsson-r/commercesystem-api/blob/main/routes/api.php) (API routes), [`app/Http/Controllers/OrderController.php`](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/OrderController.php) (Order lifecycle), [`app/Services/StockService.php`](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Services/StockService.php) (Stock ledger service), [`app/Models/Stock.php`](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Models/Stock.php) (Branch stock and logs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and identity"]
  node_api["API routes<br/>[api.php]"]
  node_identity["Authentication and access<br/>[AuthController.php]"]
end

subgraph group_commerce["Commerce workflows"]
  node_catalog["Product discovery"]
  node_cart["Cart and wishlist<br/>[CartController.php]"]
  node_orders["Order lifecycle"]
  node_sales["POS sales<br/>[SaleController.php]"]
  node_productdata[("Product catalog data<br/>[Product.php]")]
  node_transactions[("Orders and sales data<br/>[Order.php]")]
  node_preview["Visual previews"]
end

subgraph group_inventory["Inventory operations"]
  node_purchasing["Purchasing and returns"]
  node_transfers["Branch transfers"]
  node_stockservice["Stock ledger service<br/>[StockService.php]"]
  node_stockdata[("Branch stock and logs<br/>[Stock.php]")]
end

subgraph group_intelligence["AI and insights"]
  node_aiapi["AI endpoints<br/>[AIController.php]"]
  node_ai["AI orchestration"]
  node_reports["Operational reports"]
end

subgraph group_events["Events and notifications"]
  node_events{{"Domain events<br/>[OrderCreated.php]"}}
  node_eventwiring["Event registration"]
  node_listeners["Metrics and notifications"]
  node_broadcast["Realtime and push delivery"]
end

node_clients(("Store and POS clients"))
node_google["Google AI services"]

node_clients -->|"request"| node_api
node_api -->|"routes to"| node_identity
node_api -->|"routes to"| node_catalog
node_api -->|"routes to"| node_cart
node_api -->|"routes to"| node_orders
node_api -->|"routes to"| node_sales
node_api -->|"routes to"| node_purchasing
node_api -->|"routes to"| node_transfers
node_api -->|"routes to"| node_reports
node_api -->|"routes to"| node_aiapi
node_api -->|"routes to"| node_preview
node_catalog -->|"queries"| node_productdata
node_catalog -->|"queries"| node_stockdata
node_orders -->|"creates and updates"| node_transactions
node_orders -->|"checks stock"| node_stockdata
node_orders -->|"uses"| node_stockservice
node_orders -->|"dispatches"| node_events
node_sales -->|"uses"| node_stockservice
node_sales -->|"dispatches"| node_events
node_stockservice -->|"updates"| node_stockdata
node_purchasing -.->|"uses"| node_stockservice
node_transfers -.->|"uses"| node_stockservice
node_aiapi -->|"delegates to"| node_ai
node_ai -->|"calls models"| node_google
node_ai -->|"queries recommendations"| node_productdata
node_ai -->|"uses inventory data"| node_stockdata
node_reports -->|"aggregates sales"| node_transactions
node_reports -->|"reads audit data"| node_stockdata
node_eventwiring -->|"registers listeners"| node_events
node_eventwiring -->|"registers"| node_listeners
node_listeners -.->|"sends notifications"| node_broadcast

click node_api "https://github.com/ecarlsson-r/commercesystem-api/blob/main/routes/api.php"
click node_identity "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/AuthController.php"
click node_catalog "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/ProductController.php"
click node_cart "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/CartController.php"
click node_orders "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/OrderController.php"
click node_sales "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/SaleController.php"
click node_purchasing "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/PurchaseController.php"
click node_transfers "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/StockTransferController.php"
click node_stockservice "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Services/StockService.php"
click node_stockdata "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Models/Stock.php"
click node_productdata "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Models/Product.php"
click node_transactions "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Models/Order.php"
click node_aiapi "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/AIController.php"
click node_ai "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Services/LaravelAiKitService.php"
click node_reports "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/ReportController.php"
click node_preview "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/PreviewController.php"
click node_events "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Events/OrderCreated.php"
click node_eventwiring "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Providers/EventServiceProvider.php"
click node_listeners "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Listeners/RecordOrderConversion.php"
click node_broadcast "https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Notifications/OrderNotification.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_api,node_identity,node_clients toneBlue
class node_catalog,node_cart,node_orders,node_sales,node_productdata,node_transactions,node_preview toneAmber
class node_purchasing,node_transfers,node_stockservice,node_stockdata toneMint
class node_aiapi,node_ai,node_reports toneRose
class node_events,node_eventwiring,node_listeners,node_broadcast,node_google toneIndigo
```

## Components

### API and identity

- [API routes](https://github.com/ecarlsson-r/commercesystem-api/blob/main/routes/api.php): `routes/api.php`
- [Authentication and access](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/AuthController.php): `app/Http/Controllers/AuthController.php`

### Commerce workflows

- [Product discovery](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/ProductController.php): `app/Http/Controllers/ProductController.php`
- [Cart and wishlist](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/CartController.php): `app/Http/Controllers/CartController.php`
- [Order lifecycle](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/OrderController.php): `app/Http/Controllers/OrderController.php`
- [POS sales](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/SaleController.php): `app/Http/Controllers/SaleController.php`
- [Product catalog data](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Models/Product.php): `app/Models/Product.php`
- [Orders and sales data](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Models/Order.php): `app/Models/Order.php`
- [Visual previews](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/PreviewController.php): `app/Http/Controllers/PreviewController.php`

### Inventory operations

- [Purchasing and returns](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/PurchaseController.php): `app/Http/Controllers/PurchaseController.php`
- [Branch transfers](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/StockTransferController.php): `app/Http/Controllers/StockTransferController.php`
- [Stock ledger service](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Services/StockService.php): `app/Services/StockService.php`
- [Branch stock and logs](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Models/Stock.php): `app/Models/Stock.php`

### AI and insights

- [AI endpoints](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/AIController.php): `app/Http/Controllers/AIController.php`
- [AI orchestration](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Services/LaravelAiKitService.php): `app/Services/LaravelAiKitService.php`
- [Operational reports](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Http/Controllers/ReportController.php): `app/Http/Controllers/ReportController.php`

### Events and notifications

- [Domain events](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Events/OrderCreated.php): `app/Events/OrderCreated.php`
- [Event registration](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Providers/EventServiceProvider.php): `app/Providers/EventServiceProvider.php`
- [Metrics and notifications](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Listeners/RecordOrderConversion.php): `app/Listeners/RecordOrderConversion.php`
- [Realtime and push delivery](https://github.com/ecarlsson-r/commercesystem-api/blob/main/app/Notifications/OrderNotification.php): `app/Notifications/OrderNotification.php`

### Other components

- **Store and POS clients**
- **Google AI services**

## Connections

- Store and POS clients → API routes: request (evidence: `README.md`)
- API routes → Authentication and access: routes to (evidence: `routes/api.php`)
- API routes → Product discovery: routes to (evidence: `routes/api.php`)
- API routes → Cart and wishlist: routes to (evidence: `routes/api.php`)
- API routes → Order lifecycle: routes to (evidence: `routes/api.php`)
- API routes → POS sales: routes to (evidence: `routes/api.php`)
- API routes → Purchasing and returns: routes to (evidence: `routes/api.php`)
- API routes → Branch transfers: routes to (evidence: `routes/api.php`)
- API routes → Operational reports: routes to (evidence: `routes/api.php`)
- API routes → AI endpoints: routes to (evidence: `routes/api.php`)
- API routes → Visual previews: routes to (evidence: `routes/api.php`)
- Product discovery → Product catalog data: queries (evidence: `app/Http/Controllers/ProductController.php`)
- Product discovery → Branch stock and logs: queries (evidence: `app/Http/Controllers/ProductController.php`)
- Order lifecycle → Orders and sales data: creates and updates (evidence: `app/Http/Controllers/OrderController.php`)
- Order lifecycle → Branch stock and logs: checks stock (evidence: `app/Http/Controllers/OrderController.php`)
- Order lifecycle → Stock ledger service: uses (evidence: `app/Http/Controllers/OrderController.php`)
- Order lifecycle → Domain events: dispatches (evidence: `app/Http/Controllers/OrderController.php`)
- POS sales → Stock ledger service: uses (evidence: `app/Http/Controllers/SaleController.php`)
- POS sales → Domain events: dispatches (evidence: `app/Http/Controllers/SaleController.php`)
- Stock ledger service → Branch stock and logs: updates (evidence: `app/Services/StockService.php`)
- Purchasing and returns → Stock ledger service: uses
- Branch transfers → Stock ledger service: uses
- AI endpoints → AI orchestration: delegates to (evidence: `app/Http/Controllers/AIController.php`)
- AI orchestration → Google AI services: calls models (evidence: `README.md`)
- AI orchestration → Product catalog data: queries recommendations (evidence: `app/Services/LaravelAiKitService.php`)
- AI orchestration → Branch stock and logs: uses inventory data (evidence: `app/Services/LaravelAiKitService.php`)
- Operational reports → Orders and sales data: aggregates sales (evidence: `app/Http/Controllers/ReportController.php`)
- Operational reports → Branch stock and logs: reads audit data (evidence: `app/Http/Controllers/ReportController.php`)
- Event registration → Domain events: registers listeners (evidence: `app/Providers/EventServiceProvider.php`)
- Event registration → Metrics and notifications: registers (evidence: `app/Providers/EventServiceProvider.php`)
- Metrics and notifications → Realtime and push delivery: sends notifications
