# stablelife11-commits/retail-flow-backend architecture

> Architecture diagram of the GitHub repository stablelife11-commits/retail-flow-backend, 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/stablelife11-commits/retail-flow-backend
- Repository: https://github.com/stablelife11-commits/retail-flow-backend

## Overview

Retail Flow is a Spring backend for retail operations: users authenticate, maintain product and customer data, and record purchases, sales, orders, payments, and returns; a dashboard aggregates business totals. The sampled services show stock changes during purchases, sales, orders, and returns, with purchase and sale services also writing inventory audit transactions. The graph emphasizes these domain stages and reporting. Several controller-to-service links are supported by the SOURCE INDEX; unsampled subsystem relationships are omitted rather than inferred from naming alone.

Main entry points: [`src/main/java/com/retail/flow/purchase/service/PurchaseService.java`](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/purchase/service/PurchaseService.java) (Purchasing), [`src/main/java/com/retail/flow/sale/service/SaleService.java`](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/sale/service/SaleService.java) (Sales), [`src/main/java/com/retail/flow/product/repository/ProductVariantRepository.java`](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/product/repository/ProductVariantRepository.java) (Product variants), [`src/main/java/com/retail/flow/auth/service/AuthService.java`](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/auth/service/AuthService.java) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and access"]
  node_user["User accounts<br/>[User.java]"]
  node_auth_api["Authentication API"]
  node_auth_service["Authentication<br/>[AuthService.java]"]
  node_jwt["JWT tokens"]
end

subgraph group_catalog["Retail records"]
  node_product_api["Product API"]
  node_product_service["Product catalog"]
  node_product_store["Product records"]
  node_customer["Customer records"]
  node_supplier["Supplier records"]
  node_expense["Expense records"]
end

subgraph group_stock["Stock and transactions"]
  node_purchase_api["Purchase API"]
  node_purchase_service["Purchasing"]
  node_purchase_store["Purchase records"]
  node_variant_store["Product variants"]
  node_inventory_audit["Inventory audit"]
end

subgraph group_commerce["Commerce operations"]
  node_sale_api["Sale API"]
  node_sale_service["Sales<br/>[SaleService.java]"]
  node_sale_store["Sale records"]
  node_order["Customer orders<br/>[OrderService.java]"]
  node_payment["Payment records"]
  node_returns["Sale returns<br/>[ReturnService.java]"]
end

subgraph group_insights["Reporting"]
  node_report_api["Dashboard API"]
  node_report_service["Dashboard summary<br/>[ReportService.java]"]
end

node_actor(("Retail user"))

node_actor -.->|"submits credentials"| node_auth_api
node_auth_api -.->|"delegates"| node_auth_service
node_auth_service -->|"reads and saves"| node_user
node_auth_service -->|"generates token"| node_jwt
node_actor -.->|"manages catalog"| node_product_api
node_product_api -->|"delegates"| node_product_service
node_product_service -->|"saves and reads"| node_product_store
node_actor -.->|"records purchase"| node_purchase_api
node_purchase_api -->|"delegates"| node_purchase_service
node_purchase_service -->|"saves purchases"| node_purchase_store
node_purchase_service -->|"updates stock"| node_variant_store
node_purchase_service -->|"records movement"| node_inventory_audit
node_purchase_service -->|"looks up supplier"| node_supplier
node_actor -.->|"records sale"| node_sale_api
node_sale_api -.->|"delegates"| node_sale_service
node_sale_service -->|"saves and reads"| node_sale_store
node_sale_service -->|"checks and updates stock"| node_variant_store
node_sale_service -->|"records movement"| node_inventory_audit
node_actor -.->|"requests summary"| node_report_api
node_report_api -.->|"delegates"| node_report_service
node_report_service -->|"reads totals"| node_sale_store
node_report_service -->|"reads totals"| node_purchase_store
node_actor -.->|"places order"| node_order
node_order -->|"checks and updates stock"| node_variant_store
node_actor -.->|"records payment"| node_payment
node_actor -.->|"requests return"| node_returns
node_returns -->|"restores stock"| node_variant_store

click node_user "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/user/entity/User.java"
click node_auth_api "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/auth/controller/AuthController.java"
click node_auth_service "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/auth/service/AuthService.java"
click node_jwt "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/common/security/JwtTokenProvider.java"
click node_product_api "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/product/controller/ProductController.java"
click node_product_service "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/product/service/ProductService.java"
click node_product_store "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/product/repository/ProductRepository.java"
click node_customer "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/customer/service/CustomerService.java"
click node_supplier "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/supplier/service/SupplierService.java"
click node_expense "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/expense/service/ExpenseService.java"
click node_purchase_api "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/purchase/controller/PurchaseController.java"
click node_purchase_service "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/purchase/service/PurchaseService.java"
click node_purchase_store "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/purchase/repository/PurchaseRepository.java"
click node_variant_store "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/product/repository/ProductVariantRepository.java"
click node_inventory_audit "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/inventory/repository/InventoryTransactionRepository.java"
click node_sale_api "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/sale/controller/SaleController.java"
click node_sale_service "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/sale/service/SaleService.java"
click node_sale_store "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/sale/repository/SaleRepository.java"
click node_order "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/order/service/OrderService.java"
click node_payment "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/payment/service/PaymentService.java"
click node_returns "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/returns/service/ReturnService.java"
click node_report_api "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/report/controller/ReportController.java"
click node_report_service "https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/report/service/ReportService.java"

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_user,node_auth_api,node_auth_service,node_jwt,node_actor toneBlue
class node_product_api,node_product_service,node_product_store,node_customer,node_supplier,node_expense toneAmber
class node_purchase_api,node_purchase_service,node_purchase_store,node_variant_store,node_inventory_audit toneMint
class node_sale_api,node_sale_service,node_sale_store,node_order,node_payment,node_returns toneRose
class node_report_api,node_report_service toneIndigo
```

## Components

### Identity and access

- [User accounts](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/user/entity/User.java): `src/main/java/com/retail/flow/user/entity/User.java`
- [Authentication API](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/auth/controller/AuthController.java): `src/main/java/com/retail/flow/auth/controller/AuthController.java`
- [Authentication](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/auth/service/AuthService.java): `src/main/java/com/retail/flow/auth/service/AuthService.java`
- [JWT tokens](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/common/security/JwtTokenProvider.java): `src/main/java/com/retail/flow/common/security/JwtTokenProvider.java`

### Retail records

- [Product API](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/product/controller/ProductController.java): `src/main/java/com/retail/flow/product/controller/ProductController.java`
- [Product catalog](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/product/service/ProductService.java): `src/main/java/com/retail/flow/product/service/ProductService.java`
- [Product records](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/product/repository/ProductRepository.java): `src/main/java/com/retail/flow/product/repository/ProductRepository.java`
- [Customer records](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/customer/service/CustomerService.java): `src/main/java/com/retail/flow/customer/service/CustomerService.java`
- [Supplier records](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/supplier/service/SupplierService.java): `src/main/java/com/retail/flow/supplier/service/SupplierService.java`
- [Expense records](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/expense/service/ExpenseService.java): `src/main/java/com/retail/flow/expense/service/ExpenseService.java`

### Stock and transactions

- [Purchase API](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/purchase/controller/PurchaseController.java): `src/main/java/com/retail/flow/purchase/controller/PurchaseController.java`
- [Purchasing](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/purchase/service/PurchaseService.java): `src/main/java/com/retail/flow/purchase/service/PurchaseService.java`
- [Purchase records](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/purchase/repository/PurchaseRepository.java): `src/main/java/com/retail/flow/purchase/repository/PurchaseRepository.java`
- [Product variants](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/product/repository/ProductVariantRepository.java): `src/main/java/com/retail/flow/product/repository/ProductVariantRepository.java`
- [Inventory audit](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/inventory/repository/InventoryTransactionRepository.java): `src/main/java/com/retail/flow/inventory/repository/InventoryTransactionRepository.java`

### Commerce operations

- [Sale API](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/sale/controller/SaleController.java): `src/main/java/com/retail/flow/sale/controller/SaleController.java`
- [Sales](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/sale/service/SaleService.java): `src/main/java/com/retail/flow/sale/service/SaleService.java`
- [Sale records](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/sale/repository/SaleRepository.java): `src/main/java/com/retail/flow/sale/repository/SaleRepository.java`
- [Customer orders](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/order/service/OrderService.java): `src/main/java/com/retail/flow/order/service/OrderService.java`
- [Payment records](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/payment/service/PaymentService.java): `src/main/java/com/retail/flow/payment/service/PaymentService.java`
- [Sale returns](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/returns/service/ReturnService.java): `src/main/java/com/retail/flow/returns/service/ReturnService.java`

### Reporting

- [Dashboard API](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/report/controller/ReportController.java): `src/main/java/com/retail/flow/report/controller/ReportController.java`
- [Dashboard summary](https://github.com/stablelife11-commits/retail-flow-backend/blob/main/src/main/java/com/retail/flow/report/service/ReportService.java): `src/main/java/com/retail/flow/report/service/ReportService.java`

### Other components

- **Retail user**

## Connections

- Retail user → Authentication API: submits credentials
- Authentication API → Authentication: delegates (evidence: `src/main/java/com/retail/flow/auth/controller/AuthController.java`)
- Authentication → User accounts: reads and saves (evidence: `src/main/java/com/retail/flow/auth/service/AuthService.java`)
- Authentication → JWT tokens: generates token (evidence: `src/main/java/com/retail/flow/auth/service/AuthService.java`)
- Retail user → Product API: manages catalog
- Product API → Product catalog: delegates (evidence: `src/main/java/com/retail/flow/product/controller/ProductController.java`)
- Product catalog → Product records: saves and reads (evidence: `src/main/java/com/retail/flow/product/service/ProductService.java`)
- Retail user → Purchase API: records purchase
- Purchase API → Purchasing: delegates (evidence: `src/main/java/com/retail/flow/purchase/controller/PurchaseController.java`)
- Purchasing → Purchase records: saves purchases (evidence: `src/main/java/com/retail/flow/purchase/service/PurchaseService.java`)
- Purchasing → Product variants: updates stock (evidence: `src/main/java/com/retail/flow/purchase/service/PurchaseService.java`)
- Purchasing → Inventory audit: records movement (evidence: `src/main/java/com/retail/flow/purchase/service/PurchaseService.java`)
- Purchasing → Supplier records: looks up supplier (evidence: `src/main/java/com/retail/flow/purchase/service/PurchaseService.java`)
- Retail user → Sale API: records sale
- Sale API → Sales: delegates (evidence: `src/main/java/com/retail/flow/sale/controller/SaleController.java`)
- Sales → Sale records: saves and reads (evidence: `src/main/java/com/retail/flow/sale/service/SaleService.java`)
- Sales → Product variants: checks and updates stock (evidence: `src/main/java/com/retail/flow/sale/service/SaleService.java`)
- Sales → Inventory audit: records movement (evidence: `src/main/java/com/retail/flow/sale/service/SaleService.java`)
- Retail user → Dashboard API: requests summary
- Dashboard API → Dashboard summary: delegates (evidence: `src/main/java/com/retail/flow/report/controller/ReportController.java`)
- Dashboard summary → Sale records: reads totals (evidence: `src/main/java/com/retail/flow/report/service/ReportService.java`)
- Dashboard summary → Purchase records: reads totals (evidence: `src/main/java/com/retail/flow/report/service/ReportService.java`)
- Retail user → Customer orders: places order
- Customer orders → Product variants: checks and updates stock (evidence: `src/main/java/com/retail/flow/order/service/OrderService.java`)
- Retail user → Payment records: records payment
- Retail user → Sale returns: requests return
- Sale returns → Product variants: restores stock (evidence: `src/main/java/com/retail/flow/returns/service/ReturnService.java`)
