# ngocquang95/stallwise architecture

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

- Interactive diagram: https://gitdiagram.com/ngocquang95/stallwise
- Repository: https://github.com/ngocquang95/stallwise

## Overview

Stallwise is a self-hosted shop operations app for consolidating marketplace and in-person sales, managing products and stock, and tracking revenue and gross profit. The main workflow is to map and import marketplace exports or enter orders, manage their lifecycle, and reflect sales and returns in the stock ledger; dashboard and export features help review results. The graph highlights sampled service calls and documented capabilities. Several UI pages and backend controllers are present in the tree but were not sampled, so their internal wiring is not inferred.

Main entry points: [`frontend/src/app/api/backend/[...path]/route.ts`](https://github.com/ngocquang95/stallwise/blob/main/frontend/src/app/api/backend/%5B...path%5D/route.ts) (Backend API proxy), [`backend/src/main/java/dev/ngocquang/stallwise/order/OrderService.java`](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/order/OrderService.java) (Order lifecycle), [`backend/src/main/java/dev/ngocquang/stallwise/importer/ImportService.java`](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/importer/ImportService.java) (File import), [`frontend/src/components/imports/import-wizard.tsx`](https://github.com/ngocquang95/stallwise/blob/main/frontend/src/components/imports/import-wizard.tsx) (Import wizard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Shop interface"]
  node_ui["Shop workspace"]
  node_loginui["Login screen<br/>[page.tsx]"]
  node_api["Backend API proxy<br/>[route.ts]"]
  node_authroute["Login route<br/>[route.ts]"]
  node_importui["Import wizard<br/>[import-wizard.tsx]"]
  node_dashboardui["Dashboard view<br/>[dashboard-view.tsx]"]
end

subgraph group_access["Identity and setup"]
  node_auth["JWT authentication<br/>[AuthService.java]"]
  node_security["Role security"]
end

subgraph group_sales["Orders and catalog"]
  node_product["Product catalog"]
  node_productdata[("Product records<br/>[Product.java]")]
  node_channel["Sales channels"]
  node_orders["Order lifecycle<br/>[OrderService.java]"]
  node_orderdata[("Order records<br/>[SalesOrder.java]")]
end

subgraph group_stockimport["Imports and stock"]
  node_import["File import<br/>[ImportService.java]"]
  node_fileparse["Tabular file reader"]
  node_inventory["Stock ledger"]
  node_movementdata[("Stock movements<br/>[StockMovement.java]")]
end

subgraph group_insights["Reporting and settings"]
  node_dashboard["Dashboard metrics"]
  node_export["Order export<br/>[ExportService.java]"]
  node_settings["Shop settings"]
end

node_seller(("Shop staff"))
node_channelplatforms(("Marketplaces"))

node_seller -->|"signs in"| node_loginui
node_loginui -->|"submits credentials"| node_authroute
node_authroute -.->|"requests token"| node_auth
node_auth -->|"issues JWT"| node_security
node_seller -->|"manages shop"| node_ui
node_ui -.->|"requests backend"| node_api
node_api -.->|"routes requests"| node_orders
node_api -.->|"routes requests"| node_product
node_api -.->|"routes requests"| node_dashboard
node_channelplatforms -->|"provides exports"| node_importui
node_seller -->|"uploads export"| node_importui
node_importui -.->|"submits mapping"| node_import
node_import -->|"reads file"| node_fileparse
node_import -->|"places orders"| node_orders
node_orders -->|"records stock changes"| node_inventory
node_product -->|"records opening stock"| node_inventory
node_inventory -->|"saves movements"| node_movementdata
node_orders -->|"saves orders"| node_orderdata
node_dashboard -.->|"supplies metrics"| node_dashboardui
node_seller -->|"reviews results"| node_dashboardui
node_seller -->|"exports orders"| node_export
node_seller -->|"configures shop"| node_settings

click node_ui "https://github.com/ngocquang95/stallwise/tree/main/frontend/src/app/(app)"
click node_loginui "https://github.com/ngocquang95/stallwise/blob/main/frontend/src/app/login/page.tsx"
click node_api "https://github.com/ngocquang95/stallwise/blob/main/frontend/src/app/api/backend/%5B...path%5D/route.ts"
click node_authroute "https://github.com/ngocquang95/stallwise/blob/main/frontend/src/app/api/auth/login/route.ts"
click node_auth "https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/auth/AuthService.java"
click node_security "https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/config/SecurityConfig.java"
click node_product "https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/product/ProductService.java"
click node_productdata "https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/product/Product.java"
click node_channel "https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/channel/ChannelService.java"
click node_orders "https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/order/OrderService.java"
click node_orderdata "https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/order/SalesOrder.java"
click node_importui "https://github.com/ngocquang95/stallwise/blob/main/frontend/src/components/imports/import-wizard.tsx"
click node_import "https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/importer/ImportService.java"
click node_fileparse "https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/importer/TabularFileReader.java"
click node_inventory "https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/inventory/InventoryService.java"
click node_movementdata "https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/inventory/StockMovement.java"
click node_dashboard "https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/report/DashboardService.java"
click node_export "https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/report/ExportService.java"
click node_settings "https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/settings/SettingsService.java"
click node_dashboardui "https://github.com/ngocquang95/stallwise/blob/main/frontend/src/components/dashboard/dashboard-view.tsx"

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_loginui,node_api,node_authroute,node_importui,node_dashboardui toneBlue
class node_auth,node_security toneAmber
class node_product,node_productdata,node_channel,node_orders,node_orderdata toneMint
class node_import,node_fileparse,node_inventory,node_movementdata toneRose
class node_dashboard,node_export,node_settings,node_seller,node_channelplatforms toneIndigo
```

## Components

### Shop interface

- [Shop workspace](https://github.com/ngocquang95/stallwise/tree/main/frontend/src/app/(app)): `frontend/src/app/(app)`
- [Login screen](https://github.com/ngocquang95/stallwise/blob/main/frontend/src/app/login/page.tsx): `frontend/src/app/login/page.tsx`
- [Backend API proxy](https://github.com/ngocquang95/stallwise/blob/main/frontend/src/app/api/backend/%5B...path%5D/route.ts): `frontend/src/app/api/backend/[...path]/route.ts`
- [Login route](https://github.com/ngocquang95/stallwise/blob/main/frontend/src/app/api/auth/login/route.ts): `frontend/src/app/api/auth/login/route.ts`
- [Import wizard](https://github.com/ngocquang95/stallwise/blob/main/frontend/src/components/imports/import-wizard.tsx): `frontend/src/components/imports/import-wizard.tsx`
- [Dashboard view](https://github.com/ngocquang95/stallwise/blob/main/frontend/src/components/dashboard/dashboard-view.tsx): `frontend/src/components/dashboard/dashboard-view.tsx`

### Identity and setup

- [JWT authentication](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/auth/AuthService.java): `backend/src/main/java/dev/ngocquang/stallwise/auth/AuthService.java`
- [Role security](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/config/SecurityConfig.java): `backend/src/main/java/dev/ngocquang/stallwise/config/SecurityConfig.java`

### Orders and catalog

- [Product catalog](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/product/ProductService.java): `backend/src/main/java/dev/ngocquang/stallwise/product/ProductService.java`
- [Product records](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/product/Product.java): `backend/src/main/java/dev/ngocquang/stallwise/product/Product.java`
- [Sales channels](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/channel/ChannelService.java): `backend/src/main/java/dev/ngocquang/stallwise/channel/ChannelService.java`
- [Order lifecycle](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/order/OrderService.java): `backend/src/main/java/dev/ngocquang/stallwise/order/OrderService.java`
- [Order records](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/order/SalesOrder.java): `backend/src/main/java/dev/ngocquang/stallwise/order/SalesOrder.java`

### Imports and stock

- [File import](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/importer/ImportService.java): `backend/src/main/java/dev/ngocquang/stallwise/importer/ImportService.java`
- [Tabular file reader](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/importer/TabularFileReader.java): `backend/src/main/java/dev/ngocquang/stallwise/importer/TabularFileReader.java`
- [Stock ledger](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/inventory/InventoryService.java): `backend/src/main/java/dev/ngocquang/stallwise/inventory/InventoryService.java`
- [Stock movements](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/inventory/StockMovement.java): `backend/src/main/java/dev/ngocquang/stallwise/inventory/StockMovement.java`

### Reporting and settings

- [Dashboard metrics](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/report/DashboardService.java): `backend/src/main/java/dev/ngocquang/stallwise/report/DashboardService.java`
- [Order export](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/report/ExportService.java): `backend/src/main/java/dev/ngocquang/stallwise/report/ExportService.java`
- [Shop settings](https://github.com/ngocquang95/stallwise/blob/main/backend/src/main/java/dev/ngocquang/stallwise/settings/SettingsService.java): `backend/src/main/java/dev/ngocquang/stallwise/settings/SettingsService.java`

### Other components

- **Shop staff**
- **Marketplaces**

## Connections

- Shop staff → Login screen: signs in (evidence: `README.md`)
- Login screen → Login route: submits credentials (evidence: `frontend/src/app/api/auth/login/route.ts`)
- Login route → JWT authentication: requests token
- JWT authentication → Role security: issues JWT (evidence: `backend/src/main/java/dev/ngocquang/stallwise/auth/AuthService.java`)
- Shop staff → Shop workspace: manages shop (evidence: `README.md`)
- Shop workspace → Backend API proxy: requests backend
- Backend API proxy → Order lifecycle: routes requests
- Backend API proxy → Product catalog: routes requests
- Backend API proxy → Dashboard metrics: routes requests
- Marketplaces → Import wizard: provides exports (evidence: `README.md`)
- Shop staff → Import wizard: uploads export (evidence: `README.md`)
- Import wizard → File import: submits mapping
- File import → Tabular file reader: reads file (evidence: `backend/src/main/java/dev/ngocquang/stallwise/importer/ImportService.java`)
- File import → Order lifecycle: places orders (evidence: `backend/src/main/java/dev/ngocquang/stallwise/importer/ImportService.java`)
- Order lifecycle → Stock ledger: records stock changes (evidence: `backend/src/main/java/dev/ngocquang/stallwise/order/OrderService.java`)
- Product catalog → Stock ledger: records opening stock (evidence: `backend/src/main/java/dev/ngocquang/stallwise/product/ProductService.java`)
- Stock ledger → Stock movements: saves movements (evidence: `backend/src/main/java/dev/ngocquang/stallwise/inventory/InventoryService.java`)
- Order lifecycle → Order records: saves orders (evidence: `backend/src/main/java/dev/ngocquang/stallwise/order/OrderService.java`)
- Dashboard metrics → Dashboard view: supplies metrics
- Shop staff → Dashboard view: reviews results (evidence: `README.md`)
- Shop staff → Order export: exports orders (evidence: `README.md`)
- Shop staff → Shop settings: configures shop (evidence: `README.md`)