# luthfibg/pos_retail architecture

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

- Interactive diagram: https://gitdiagram.com/luthfibg/pos_retail
- Repository: https://github.com/luthfibg/pos_retail

## Overview

POS Retail SMK is a multi-store retail point-of-sale system with employee credit sales and combined HR billing. Users sign in, work in the selected store, and use product/inventory workflows; the documented target also covers purchasing, sales, shifts, invoicing, reporting, and stock counts. The README cautions that purchasing, POS, shifts, and invoices are still incomplete. The graph combines documented product areas with sampled inventory-count, authorization, and supplier-return implementation; unsampled feature internals and most frontend-to-API links are not asserted.

Main entry points: [`backend/app/Http/Controllers/OpnameSessionController.php`](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Http/Controllers/OpnameSessionController.php) (Count session API), [`backend/config/database.php`](https://github.com/luthfibg/pos_retail/blob/main/backend/config/database.php) (MySQL store), [`backend/app/Services/PermissionResolver.php`](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/PermissionResolver.php) (Permission resolver), [`backend/app/Services/AuditLogger.php`](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/AuditLogger.php) (Audit trail)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Storefront"]
  node_ui["Retail workspace"]
  node_api["API client<br/>[client.ts]"]
end

subgraph group_identity["Identity and access"]
  node_auth["Login and session<br/>[AuthProvider.tsx]"]
  node_user["User identity<br/>[User.php]"]
  node_store["Store context<br/>[StoreContext.php]"]
  node_permissions["Permission resolver"]
  node_authkeys["Approval keys"]
end

subgraph group_stock["Inventory operations"]
  node_opnameui["Count workspace"]
  node_offline[("Offline count queue")]
  node_opnameapi["Count session API"]
  node_sessions["Session lifecycle"]
  node_counting["Count recording"]
  node_progress["Count progress"]
  node_history["Count history"]
  node_workflow["Count approval"]
  node_supplierreturn["Supplier returns"]
end

subgraph group_commerce["Retail operations"]
  node_sales["Sales and credit<br/>[SaleService.php]"]
  node_purchasing["Purchasing"]
  node_shifts["Cash shifts<br/>[ShiftService.php]"]
  node_billing["HR billing<br/>[BillingService.php]"]
  node_reports["Reports<br/>[ReportService.php]"]
end

subgraph group_platform["Platform services"]
  node_audit[("Audit trail<br/>[AuditLogger.php]")]
  node_db[("MySQL store<br/>[database.php]")]
end

node_clerk(("Store staff"))

node_clerk -->|"uses"| node_ui
node_ui -.->|"requests data"| node_api
node_api -.->|"supports session"| node_auth
node_auth -.->|"authenticates"| node_user
node_opnameui -->|"queues counts"| node_offline
node_opnameui -.->|"submits counts"| node_opnameapi
node_opnameapi -->|"resolves store"| node_store
node_opnameapi -->|"starts sessions"| node_sessions
node_opnameapi -->|"records counts"| node_counting
node_opnameapi -->|"loads progress"| node_progress
node_opnameapi -->|"loads history"| node_history
node_opnameapi -->|"runs workflow"| node_workflow
node_opnameapi -->|"checks access"| node_permissions
node_sessions -->|"records events"| node_audit
node_authkeys -->|"records changes"| node_audit
node_permissions -->|"resolves store"| node_store
node_permissions -->|"checks identity"| node_user
node_supplierreturn -.->|"records changes"| node_audit
node_sales -.->|"persists sales"| node_db
node_purchasing -.->|"persists orders"| node_db
node_shifts -.->|"persists shifts"| node_db
node_billing -.->|"stores invoices"| node_db
node_reports -.->|"reads reports"| node_db

click node_ui "https://github.com/luthfibg/pos_retail/tree/main/frontend/src/features"
click node_api "https://github.com/luthfibg/pos_retail/blob/main/frontend/src/lib/api/client.ts"
click node_auth "https://github.com/luthfibg/pos_retail/blob/main/frontend/src/features/auth/AuthProvider.tsx"
click node_user "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Models/User.php"
click node_store "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/StoreContext.php"
click node_permissions "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/PermissionResolver.php"
click node_authkeys "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/AuthorizationKeyService.php"
click node_opnameui "https://github.com/luthfibg/pos_retail/blob/main/frontend/src/features/inventory/OpnameSessionsPage.tsx"
click node_offline "https://github.com/luthfibg/pos_retail/blob/main/frontend/src/features/inventory/opnameOfflineStore.ts"
click node_opnameapi "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Http/Controllers/OpnameSessionController.php"
click node_sessions "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/OpnameSessionService.php"
click node_counting "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/OpnameCountService.php"
click node_progress "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/OpnameProgressService.php"
click node_history "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/OpnameHistoryService.php"
click node_workflow "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/OpnameWorkflowService.php"
click node_supplierreturn "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/SupplierReturnService.php"
click node_sales "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/SaleService.php"
click node_purchasing "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/PurchaseOrderService.php"
click node_shifts "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/ShiftService.php"
click node_billing "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/BillingService.php"
click node_reports "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/ReportService.php"
click node_audit "https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/AuditLogger.php"
click node_db "https://github.com/luthfibg/pos_retail/blob/main/backend/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_ui,node_api toneBlue
class node_auth,node_user,node_store,node_permissions,node_authkeys toneAmber
class node_opnameui,node_offline,node_opnameapi,node_sessions,node_counting,node_progress,node_history,node_workflow,node_supplierreturn toneMint
class node_sales,node_purchasing,node_shifts,node_billing,node_reports toneRose
class node_audit,node_db,node_clerk toneIndigo
```

## Components

### Storefront

- [Retail workspace](https://github.com/luthfibg/pos_retail/tree/main/frontend/src/features): `frontend/src/features`
- [API client](https://github.com/luthfibg/pos_retail/blob/main/frontend/src/lib/api/client.ts): `frontend/src/lib/api/client.ts`

### Identity and access

- [Login and session](https://github.com/luthfibg/pos_retail/blob/main/frontend/src/features/auth/AuthProvider.tsx): `frontend/src/features/auth/AuthProvider.tsx`
- [User identity](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Models/User.php): `backend/app/Models/User.php`
- [Store context](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/StoreContext.php): `backend/app/Services/StoreContext.php`
- [Permission resolver](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/PermissionResolver.php): `backend/app/Services/PermissionResolver.php`
- [Approval keys](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/AuthorizationKeyService.php): `backend/app/Services/AuthorizationKeyService.php`

### Inventory operations

- [Count workspace](https://github.com/luthfibg/pos_retail/blob/main/frontend/src/features/inventory/OpnameSessionsPage.tsx): `frontend/src/features/inventory/OpnameSessionsPage.tsx`
- [Offline count queue](https://github.com/luthfibg/pos_retail/blob/main/frontend/src/features/inventory/opnameOfflineStore.ts): `frontend/src/features/inventory/opnameOfflineStore.ts`
- [Count session API](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Http/Controllers/OpnameSessionController.php): `backend/app/Http/Controllers/OpnameSessionController.php`
- [Session lifecycle](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/OpnameSessionService.php): `backend/app/Services/OpnameSessionService.php`
- [Count recording](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/OpnameCountService.php): `backend/app/Services/OpnameCountService.php`
- [Count progress](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/OpnameProgressService.php): `backend/app/Services/OpnameProgressService.php`
- [Count history](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/OpnameHistoryService.php): `backend/app/Services/OpnameHistoryService.php`
- [Count approval](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/OpnameWorkflowService.php): `backend/app/Services/OpnameWorkflowService.php`
- [Supplier returns](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/SupplierReturnService.php): `backend/app/Services/SupplierReturnService.php`

### Retail operations

- [Sales and credit](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/SaleService.php): `backend/app/Services/SaleService.php`
- [Purchasing](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/PurchaseOrderService.php): `backend/app/Services/PurchaseOrderService.php`
- [Cash shifts](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/ShiftService.php): `backend/app/Services/ShiftService.php`
- [HR billing](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/BillingService.php): `backend/app/Services/BillingService.php`
- [Reports](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/ReportService.php): `backend/app/Services/ReportService.php`

### Platform services

- [Audit trail](https://github.com/luthfibg/pos_retail/blob/main/backend/app/Services/AuditLogger.php): `backend/app/Services/AuditLogger.php`
- [MySQL store](https://github.com/luthfibg/pos_retail/blob/main/backend/config/database.php): `backend/config/database.php`

### Other components

- **Store staff**

## Connections

- Store staff → Retail workspace: uses (evidence: `README.md`)
- Retail workspace → API client: requests data
- API client → Login and session: supports session
- Login and session → User identity: authenticates
- Count workspace → Offline count queue: queues counts
- Count workspace → Count session API: submits counts
- Count session API → Store context: resolves store (evidence: `backend/app/Http/Controllers/OpnameSessionController.php`)
- Count session API → Session lifecycle: starts sessions (evidence: `backend/app/Http/Controllers/OpnameSessionController.php`)
- Count session API → Count recording: records counts (evidence: `backend/app/Http/Controllers/OpnameSessionController.php`)
- Count session API → Count progress: loads progress (evidence: `backend/app/Http/Controllers/OpnameSessionController.php`)
- Count session API → Count history: loads history (evidence: `backend/app/Http/Controllers/OpnameSessionController.php`)
- Count session API → Count approval: runs workflow (evidence: `backend/app/Http/Controllers/OpnameSessionController.php`)
- Count session API → Permission resolver: checks access (evidence: `backend/app/Http/Controllers/OpnameSessionController.php`)
- Session lifecycle → Audit trail: records events (evidence: `backend/app/Services/OpnameSessionService.php`)
- Approval keys → Audit trail: records changes (evidence: `backend/app/Services/AuthorizationKeyService.php`)
- Permission resolver → Store context: resolves store (evidence: `backend/app/Services/PermissionResolver.php`)
- Permission resolver → User identity: checks identity (evidence: `backend/app/Services/PermissionResolver.php`)
- Supplier returns → Audit trail: records changes
- Sales and credit → MySQL store: persists sales
- Purchasing → MySQL store: persists orders
- Cash shifts → MySQL store: persists shifts
- HR billing → MySQL store: stores invoices
- Reports → MySQL store: reads reports