# sakouksa/khposcommerce architecture

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

- Interactive diagram: https://gitdiagram.com/sakouksa/khposcommerce
- Repository: https://github.com/sakouksa/khposcommerce

## Overview

KHPosCommerce is an omnichannel retail platform combining an admin dashboard and web POS, a customer storefront, a Laravel API, and a documented Flutter mobile POS. The main workflow is staff or customers using a client to reach the API for commerce operations and receive results; the README documents that client/API relationship. Backend review excerpts show customer review submission and a separate admin review-management path, including the service/repository layer. Flutter implementation files and most commerce handlers were not sampled, so those relationships reflect README-documented capabilities rather than inspected calls.

Main entry points: [`backendkhposcommerce/app/Http/Controllers/Api/BaseApiController.php`](https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Http/Controllers/Api/BaseApiController.php) (Laravel API), [`apps/adminkhposcommerce/src/App.tsx`](https://github.com/sakouksa/khposcommerce/blob/develop/apps/adminkhposcommerce/src/App.tsx) (Admin dashboard), [`apps/storefrontkhposcommerce/src/app/App.tsx`](https://github.com/sakouksa/khposcommerce/blob/develop/apps/storefrontkhposcommerce/src/app/App.tsx) (Storefront), [`backendkhposcommerce/app/Models/Review/ProductReview.php`](https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Models/Review/ProductReview.php) (Review records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Commerce clients"]
  node_admin["Admin dashboard<br/>[App.tsx]"]
  node_admin_routes["Admin routes<br/>[AppRoutes.tsx]"]
  node_guard["Access guard<br/>[ProtectedRoute.tsx]"]
  node_storefront["Storefront<br/>[App.tsx]"]
  node_store_routes["Store routes<br/>[routes.tsx]"]
  node_mobile_pos["Mobile POS"]
end

subgraph group_operations["Retail operations"]
  node_pos["Web POS<br/>[POSPage.tsx]"]
  node_catalog[("Product catalog<br/>[Product.php]")]
  node_inventory["Inventory operations<br/>[InventoryPage.tsx]"]
  node_orders[("Orders<br/>[Order.php]")]
  node_customers[("Customer records<br/>[Customer.php]")]
  node_marketing["Promotions and CMS<br/>[PromotionsPage.tsx]"]
  node_review_customer["Customer reviews"]
  node_review_admin["Review administration"]
end

subgraph group_backend["API and domain"]
  node_review_service["Review service"]
  node_review_repository["Review repository"]
  node_review_model[("Review records<br/>[ProductReview.php]")]
  node_api["Laravel API"]
end

subgraph group_platform["Shared platform"]
  node_auth["Authentication service<br/>[AuthService.php]"]
  node_database[("Commerce database<br/>[database.php]")]
end

node_staff(("Retail staff"))
node_shoppers(("Online shoppers"))

node_staff -->|"uses"| node_admin
node_admin -->|"loads routes"| node_admin_routes
node_admin_routes -->|"protects routes"| node_guard
node_staff -->|"uses"| node_pos
node_shoppers -->|"browses"| node_storefront
node_storefront -->|"loads routes"| node_store_routes
node_staff -->|"uses"| node_mobile_pos
node_admin -.->|"requests commerce data"| node_api
node_storefront -.->|"requests commerce data"| node_api
node_mobile_pos -.->|"uses API"| node_api
node_api -.->|"serves catalog"| node_catalog
node_api -.->|"serves stock operations"| node_inventory
node_api -.->|"handles orders"| node_orders
node_api -.->|"handles customers"| node_customers
node_api -.->|"serves promotions"| node_marketing
node_api -.->|"authenticates requests"| node_auth
node_review_customer -->|"creates review"| node_review_model
node_review_admin -->|"manages reviews"| node_review_model
node_review_admin -.->|"delegates CRUD"| node_review_service
node_review_service -->|"delegates persistence"| node_review_repository
node_review_repository -->|"queries model"| node_review_model
node_review_customer -->|"returns response"| node_api
node_api -.->|"uses configured store"| node_database

click node_admin "https://github.com/sakouksa/khposcommerce/blob/develop/apps/adminkhposcommerce/src/App.tsx"
click node_admin_routes "https://github.com/sakouksa/khposcommerce/blob/develop/apps/adminkhposcommerce/src/routes/AppRoutes.tsx"
click node_guard "https://github.com/sakouksa/khposcommerce/blob/develop/apps/adminkhposcommerce/src/routes/guards/ProtectedRoute.tsx"
click node_pos "https://github.com/sakouksa/khposcommerce/blob/develop/apps/adminkhposcommerce/src/pages/pos/POSPage.tsx"
click node_storefront "https://github.com/sakouksa/khposcommerce/blob/develop/apps/storefrontkhposcommerce/src/app/App.tsx"
click node_store_routes "https://github.com/sakouksa/khposcommerce/blob/develop/apps/storefrontkhposcommerce/src/app/router/routes.tsx"
click node_mobile_pos "https://github.com/sakouksa/khposcommerce/tree/develop/appkhposcommerce"
click node_catalog "https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Models/Product/Product.php"
click node_inventory "https://github.com/sakouksa/khposcommerce/blob/develop/apps/adminkhposcommerce/src/pages/inventory/InventoryPage.tsx"
click node_orders "https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Models/Order/Order.php"
click node_customers "https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Models/Customer/Customer.php"
click node_marketing "https://github.com/sakouksa/khposcommerce/blob/develop/apps/adminkhposcommerce/src/pages/marketing/PromotionsPage.tsx"
click node_review_customer "https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Http/Controllers/Api/V1/Customer/ReviewController.php"
click node_review_admin "https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Http/Controllers/Api/V1/Admin/Order/ReviewController.php"
click node_review_service "https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Services/Review/ProductReviewService.php"
click node_review_repository "https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Repositories/Review/ProductReviewRepository.php"
click node_review_model "https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Models/Review/ProductReview.php"
click node_api "https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Http/Controllers/Api/BaseApiController.php"
click node_auth "https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Services/Auth/AuthService.php"
click node_database "https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/config/database.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_admin,node_admin_routes,node_guard,node_storefront,node_store_routes,node_mobile_pos toneBlue
class node_pos,node_catalog,node_inventory,node_orders,node_customers,node_marketing,node_review_customer,node_review_admin toneAmber
class node_review_service,node_review_repository,node_review_model,node_api toneMint
class node_auth,node_database toneRose
class node_staff,node_shoppers toneIndigo
```

## Components

### Commerce clients

- [Admin dashboard](https://github.com/sakouksa/khposcommerce/blob/develop/apps/adminkhposcommerce/src/App.tsx): `apps/adminkhposcommerce/src/App.tsx`
- [Admin routes](https://github.com/sakouksa/khposcommerce/blob/develop/apps/adminkhposcommerce/src/routes/AppRoutes.tsx): `apps/adminkhposcommerce/src/routes/AppRoutes.tsx`
- [Access guard](https://github.com/sakouksa/khposcommerce/blob/develop/apps/adminkhposcommerce/src/routes/guards/ProtectedRoute.tsx): `apps/adminkhposcommerce/src/routes/guards/ProtectedRoute.tsx`
- [Storefront](https://github.com/sakouksa/khposcommerce/blob/develop/apps/storefrontkhposcommerce/src/app/App.tsx): `apps/storefrontkhposcommerce/src/app/App.tsx`
- [Store routes](https://github.com/sakouksa/khposcommerce/blob/develop/apps/storefrontkhposcommerce/src/app/router/routes.tsx): `apps/storefrontkhposcommerce/src/app/router/routes.tsx`
- [Mobile POS](https://github.com/sakouksa/khposcommerce/tree/develop/appkhposcommerce): `appkhposcommerce`

### Retail operations

- [Web POS](https://github.com/sakouksa/khposcommerce/blob/develop/apps/adminkhposcommerce/src/pages/pos/POSPage.tsx): `apps/adminkhposcommerce/src/pages/pos/POSPage.tsx`
- [Product catalog](https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Models/Product/Product.php): `backendkhposcommerce/app/Models/Product/Product.php`
- [Inventory operations](https://github.com/sakouksa/khposcommerce/blob/develop/apps/adminkhposcommerce/src/pages/inventory/InventoryPage.tsx): `apps/adminkhposcommerce/src/pages/inventory/InventoryPage.tsx`
- [Orders](https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Models/Order/Order.php): `backendkhposcommerce/app/Models/Order/Order.php`
- [Customer records](https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Models/Customer/Customer.php): `backendkhposcommerce/app/Models/Customer/Customer.php`
- [Promotions and CMS](https://github.com/sakouksa/khposcommerce/blob/develop/apps/adminkhposcommerce/src/pages/marketing/PromotionsPage.tsx): `apps/adminkhposcommerce/src/pages/marketing/PromotionsPage.tsx`
- [Customer reviews](https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Http/Controllers/Api/V1/Customer/ReviewController.php): `backendkhposcommerce/app/Http/Controllers/Api/V1/Customer/ReviewController.php`
- [Review administration](https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Http/Controllers/Api/V1/Admin/Order/ReviewController.php): `backendkhposcommerce/app/Http/Controllers/Api/V1/Admin/Order/ReviewController.php`

### API and domain

- [Review service](https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Services/Review/ProductReviewService.php): `backendkhposcommerce/app/Services/Review/ProductReviewService.php`
- [Review repository](https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Repositories/Review/ProductReviewRepository.php): `backendkhposcommerce/app/Repositories/Review/ProductReviewRepository.php`
- [Review records](https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Models/Review/ProductReview.php): `backendkhposcommerce/app/Models/Review/ProductReview.php`
- [Laravel API](https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Http/Controllers/Api/BaseApiController.php): `backendkhposcommerce/app/Http/Controllers/Api/BaseApiController.php`

### Shared platform

- [Authentication service](https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/app/Services/Auth/AuthService.php): `backendkhposcommerce/app/Services/Auth/AuthService.php`
- [Commerce database](https://github.com/sakouksa/khposcommerce/blob/develop/backendkhposcommerce/config/database.php): `backendkhposcommerce/config/database.php`

### Other components

- **Retail staff**
- **Online shoppers**

## Connections

- Retail staff → Admin dashboard: uses
- Admin dashboard → Admin routes: loads routes (evidence: `apps/adminkhposcommerce/src/App.tsx`)
- Admin routes → Access guard: protects routes (evidence: `apps/adminkhposcommerce/src/routes/AppRoutes.tsx`)
- Retail staff → Web POS: uses
- Online shoppers → Storefront: browses
- Storefront → Store routes: loads routes
- Retail staff → Mobile POS: uses
- Admin dashboard → Laravel API: requests commerce data
- Storefront → Laravel API: requests commerce data
- Mobile POS → Laravel API: uses API
- Laravel API → Product catalog: serves catalog
- Laravel API → Inventory operations: serves stock operations
- Laravel API → Orders: handles orders
- Laravel API → Customer records: handles customers
- Laravel API → Promotions and CMS: serves promotions
- Laravel API → Authentication service: authenticates requests
- Customer reviews → Review records: creates review (evidence: `backendkhposcommerce/app/Http/Controllers/Api/V1/Customer/ReviewController.php`)
- Review administration → Review records: manages reviews (evidence: `backendkhposcommerce/app/Http/Controllers/Api/V1/Admin/Order/ReviewController.php`)
- Review administration → Review service: delegates CRUD
- Review service → Review repository: delegates persistence (evidence: `backendkhposcommerce/app/Services/Review/ProductReviewService.php`)
- Review repository → Review records: queries model (evidence: `backendkhposcommerce/app/Repositories/Review/ProductReviewRepository.php`)
- Customer reviews → Laravel API: returns response (evidence: `backendkhposcommerce/app/Http/Controllers/Api/V1/Customer/ReviewController.php`)
- Laravel API → Commerce database: uses configured store
