# sk6594246/shelftrack architecture

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

- Interactive diagram: https://gitdiagram.com/sk6594246/shelftrack
- Repository: https://github.com/sk6594246/shelftrack

## Overview

Inventory Tracker is a mobile-friendly inventory PWA. Users browse and maintain products, scan configurable QR/barcodes to find or prefill products, and manage stock through receiving, picking, location mapping, and inventory documents. The sampled code confirms the routed app shell, product hook/store access, document posting effects, location/layout actions, and cloud API options. Several page implementations and the local/cloud selection logic were not sampled, so those links are omitted where their ownership cannot be verified.

Main entry points: [`src/App.tsx`](https://github.com/sk6594246/shelftrack/blob/main/src/App.tsx) (Route and shell), [`src/store/inventoryStore.ts`](https://github.com/sk6594246/shelftrack/blob/main/src/store/inventoryStore.ts) (Inventory store), [`src/pages/Scan.tsx`](https://github.com/sk6594246/shelftrack/blob/main/src/pages/Scan.tsx) (Scan workflow), [`src/store/documentsStore.ts`](https://github.com/sk6594246/shelftrack/blob/main/src/store/documentsStore.ts) (Document operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_app["Route and shell<br/>[App.tsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_inventory["Inventory list<br/>[Inventory.tsx]"]
  node_product["Product detail<br/>[ProductDetail.tsx]"]
  node_productform["Product form<br/>[ProductForm.tsx]"]
  node_pwa["Service worker<br/>[sw.js]"]
end

subgraph group_qr["QR workflow"]
  node_scanner["Camera scanner<br/>[QRScanner.tsx]"]
  node_scanpage["Scan workflow<br/>[Scan.tsx]"]
  node_qrlogic["QR interpretation<br/>[qr.ts]"]
  node_qrsettings["QR field mapping<br/>[QRMapping.tsx]"]
  node_qrhook["QR mapping hook<br/>[useQRMapping.ts]"]
end

subgraph group_operations["Stock operations"]
  node_documents["Document detail<br/>[DocumentDetail.tsx]"]
  node_docstore["Document operations<br/>[documentsStore.ts]"]
  node_receive["Receive dock<br/>[ReceiveDock.tsx]"]
  node_pick["Pick list<br/>[PickList.tsx]"]
  node_stockmap["Stock map<br/>[StockMap.tsx]"]
  node_masters["Master data<br/>[Masters.tsx]"]
end

subgraph group_data["Data and sync"]
  node_producthook["Product hook<br/>[useProducts.ts]"]
  node_inventorydb[("Inventory store<br/>[inventoryStore.ts]")]
  node_batchdb[("Stock batches<br/>[stockBatchStore.ts]")]
  node_syncclient["Backend API client<br/>[gasApi.ts]"]
  node_d1client["D1 API client<br/>[d1Api.ts]"]
  node_worker["D1 API worker<br/>[index.ts]"]
  node_d1store[("D1 database<br/>[actions.ts]")]
end

subgraph group_admin["Configuration"]
  node_settings["Settings<br/>[Settings.tsx]"]
  node_login["Login<br/>[Login.tsx]"]
end

node_user(("Inventory user"))
node_cloud[("Configured cloud backend")]
node_camera(("Device camera"))

node_user -->|"uses"| node_app
node_app -->|"routes"| node_dashboard
node_app -->|"routes"| node_inventory
node_app -->|"routes"| node_product
node_app -->|"routes"| node_productform
node_app -->|"routes"| node_scanpage
node_app -->|"routes"| node_receive
node_app -->|"routes"| node_pick
node_app -->|"routes"| node_stockmap
node_app -->|"routes"| node_documents
node_app -->|"routes"| node_masters
node_app -->|"routes"| node_settings
node_app -->|"routes"| node_login
node_inventory -->|"loads products"| node_producthook
node_producthook -->|"reads and writes"| node_inventorydb
node_scanpage -->|"scans code"| node_scanner
node_camera -->|"provides image"| node_scanner
node_scanpage -->|"interprets payload"| node_qrlogic
node_scanpage -->|"loads mapping"| node_qrhook
node_qrhook -->|"reads and saves mapping"| node_inventorydb
node_qrsettings -->|"updates mapping"| node_qrhook
node_documents -->|"manages documents"| node_docstore
node_docstore -->|"adjusts stock"| node_inventorydb
node_docstore -->|"receives batches"| node_batchdb
node_stockmap -->|"loads products"| node_inventorydb
node_stockmap -->|"reads quantities"| node_batchdb
node_masters -->|"loads products"| node_inventorydb
node_receive -->|"creates receiving work"| node_docstore
node_pick -->|"opens pick workflow"| node_documents
node_settings -->|"ensures tenant"| node_syncclient
node_syncclient -.->|"requests backend"| node_cloud
node_d1client -->|"posts actions"| node_worker
node_worker -->|"dispatches actions"| node_d1store
node_worker -.->|"uses configured D1"| node_cloud
node_app -->|"registers"| node_pwa

click node_app "https://github.com/sk6594246/shelftrack/blob/main/src/App.tsx"
click node_dashboard "https://github.com/sk6594246/shelftrack/blob/main/src/pages/Dashboard.tsx"
click node_inventory "https://github.com/sk6594246/shelftrack/blob/main/src/pages/Inventory.tsx"
click node_product "https://github.com/sk6594246/shelftrack/blob/main/src/pages/ProductDetail.tsx"
click node_productform "https://github.com/sk6594246/shelftrack/blob/main/src/pages/ProductForm.tsx"
click node_producthook "https://github.com/sk6594246/shelftrack/blob/main/src/hooks/useProducts.ts"
click node_scanner "https://github.com/sk6594246/shelftrack/blob/main/src/components/scanner/QRScanner.tsx"
click node_scanpage "https://github.com/sk6594246/shelftrack/blob/main/src/pages/Scan.tsx"
click node_qrlogic "https://github.com/sk6594246/shelftrack/blob/main/src/lib/qr.ts"
click node_qrsettings "https://github.com/sk6594246/shelftrack/blob/main/src/pages/settings/QRMapping.tsx"
click node_qrhook "https://github.com/sk6594246/shelftrack/blob/main/src/hooks/useQRMapping.ts"
click node_documents "https://github.com/sk6594246/shelftrack/blob/main/src/pages/documents/DocumentDetail.tsx"
click node_docstore "https://github.com/sk6594246/shelftrack/blob/main/src/store/documentsStore.ts"
click node_receive "https://github.com/sk6594246/shelftrack/blob/main/src/pages/ReceiveDock.tsx"
click node_pick "https://github.com/sk6594246/shelftrack/blob/main/src/pages/PickList.tsx"
click node_stockmap "https://github.com/sk6594246/shelftrack/blob/main/src/pages/StockMap.tsx"
click node_masters "https://github.com/sk6594246/shelftrack/blob/main/src/pages/masters/Masters.tsx"
click node_inventorydb "https://github.com/sk6594246/shelftrack/blob/main/src/store/inventoryStore.ts"
click node_batchdb "https://github.com/sk6594246/shelftrack/blob/main/src/store/stockBatchStore.ts"
click node_settings "https://github.com/sk6594246/shelftrack/blob/main/src/pages/settings/Settings.tsx"
click node_login "https://github.com/sk6594246/shelftrack/blob/main/src/pages/auth/Login.tsx"
click node_syncclient "https://github.com/sk6594246/shelftrack/blob/main/src/lib/gasApi.ts"
click node_d1client "https://github.com/sk6594246/shelftrack/blob/main/src/lib/d1Api.ts"
click node_worker "https://github.com/sk6594246/shelftrack/blob/main/worker/src/index.ts"
click node_d1store "https://github.com/sk6594246/shelftrack/blob/main/worker/src/actions.ts"
click node_pwa "https://github.com/sk6594246/shelftrack/blob/main/public/sw.js"

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_app,node_dashboard,node_inventory,node_product,node_productform,node_pwa,node_user toneBlue
class node_scanner,node_scanpage,node_qrlogic,node_qrsettings,node_qrhook,node_cloud toneAmber
class node_documents,node_docstore,node_receive,node_pick,node_stockmap,node_masters toneMint
class node_producthook,node_inventorydb,node_batchdb,node_syncclient,node_d1client,node_worker,node_d1store toneRose
class node_settings,node_login,node_camera toneIndigo
```

## Components

### App experience

- [Route and shell](https://github.com/sk6594246/shelftrack/blob/main/src/App.tsx): `src/App.tsx`
- [Dashboard](https://github.com/sk6594246/shelftrack/blob/main/src/pages/Dashboard.tsx): `src/pages/Dashboard.tsx`
- [Inventory list](https://github.com/sk6594246/shelftrack/blob/main/src/pages/Inventory.tsx): `src/pages/Inventory.tsx`
- [Product detail](https://github.com/sk6594246/shelftrack/blob/main/src/pages/ProductDetail.tsx): `src/pages/ProductDetail.tsx`
- [Product form](https://github.com/sk6594246/shelftrack/blob/main/src/pages/ProductForm.tsx): `src/pages/ProductForm.tsx`
- [Service worker](https://github.com/sk6594246/shelftrack/blob/main/public/sw.js): `public/sw.js`

### QR workflow

- [Camera scanner](https://github.com/sk6594246/shelftrack/blob/main/src/components/scanner/QRScanner.tsx): `src/components/scanner/QRScanner.tsx`
- [Scan workflow](https://github.com/sk6594246/shelftrack/blob/main/src/pages/Scan.tsx): `src/pages/Scan.tsx`
- [QR interpretation](https://github.com/sk6594246/shelftrack/blob/main/src/lib/qr.ts): `src/lib/qr.ts`
- [QR field mapping](https://github.com/sk6594246/shelftrack/blob/main/src/pages/settings/QRMapping.tsx): `src/pages/settings/QRMapping.tsx`
- [QR mapping hook](https://github.com/sk6594246/shelftrack/blob/main/src/hooks/useQRMapping.ts): `src/hooks/useQRMapping.ts`

### Stock operations

- [Document detail](https://github.com/sk6594246/shelftrack/blob/main/src/pages/documents/DocumentDetail.tsx): `src/pages/documents/DocumentDetail.tsx`
- [Document operations](https://github.com/sk6594246/shelftrack/blob/main/src/store/documentsStore.ts): `src/store/documentsStore.ts`
- [Receive dock](https://github.com/sk6594246/shelftrack/blob/main/src/pages/ReceiveDock.tsx): `src/pages/ReceiveDock.tsx`
- [Pick list](https://github.com/sk6594246/shelftrack/blob/main/src/pages/PickList.tsx): `src/pages/PickList.tsx`
- [Stock map](https://github.com/sk6594246/shelftrack/blob/main/src/pages/StockMap.tsx): `src/pages/StockMap.tsx`
- [Master data](https://github.com/sk6594246/shelftrack/blob/main/src/pages/masters/Masters.tsx): `src/pages/masters/Masters.tsx`

### Data and sync

- [Product hook](https://github.com/sk6594246/shelftrack/blob/main/src/hooks/useProducts.ts): `src/hooks/useProducts.ts`
- [Inventory store](https://github.com/sk6594246/shelftrack/blob/main/src/store/inventoryStore.ts): `src/store/inventoryStore.ts`
- [Stock batches](https://github.com/sk6594246/shelftrack/blob/main/src/store/stockBatchStore.ts): `src/store/stockBatchStore.ts`
- [Backend API client](https://github.com/sk6594246/shelftrack/blob/main/src/lib/gasApi.ts): `src/lib/gasApi.ts`
- [D1 API client](https://github.com/sk6594246/shelftrack/blob/main/src/lib/d1Api.ts): `src/lib/d1Api.ts`
- [D1 API worker](https://github.com/sk6594246/shelftrack/blob/main/worker/src/index.ts): `worker/src/index.ts`
- [D1 database](https://github.com/sk6594246/shelftrack/blob/main/worker/src/actions.ts): `worker/src/actions.ts`

### Configuration

- [Settings](https://github.com/sk6594246/shelftrack/blob/main/src/pages/settings/Settings.tsx): `src/pages/settings/Settings.tsx`
- [Login](https://github.com/sk6594246/shelftrack/blob/main/src/pages/auth/Login.tsx): `src/pages/auth/Login.tsx`

### Other components

- **Inventory user**
- **Configured cloud backend**
- **Device camera**

## Connections

- Inventory user → Route and shell: uses
- Route and shell → Dashboard: routes
- Route and shell → Inventory list: routes
- Route and shell → Product detail: routes
- Route and shell → Product form: routes
- Route and shell → Scan workflow: routes
- Route and shell → Receive dock: routes
- Route and shell → Pick list: routes
- Route and shell → Stock map: routes
- Route and shell → Document detail: routes
- Route and shell → Master data: routes
- Route and shell → Settings: routes
- Route and shell → Login: routes
- Inventory list → Product hook: loads products
- Product hook → Inventory store: reads and writes
- Scan workflow → Camera scanner: scans code
- Device camera → Camera scanner: provides image
- Scan workflow → QR interpretation: interprets payload
- Scan workflow → QR mapping hook: loads mapping
- QR mapping hook → Inventory store: reads and saves mapping
- QR field mapping → QR mapping hook: updates mapping
- Document detail → Document operations: manages documents
- Document operations → Inventory store: adjusts stock
- Document operations → Stock batches: receives batches
- Stock map → Inventory store: loads products
- Stock map → Stock batches: reads quantities
- Master data → Inventory store: loads products
- Receive dock → Document operations: creates receiving work
- Pick list → Document detail: opens pick workflow
- Settings → Backend API client: ensures tenant
- Backend API client → Configured cloud backend: requests backend
- D1 API client → D1 API worker: posts actions
- D1 API worker → D1 database: dispatches actions
- D1 API worker → Configured cloud backend: uses configured D1
- Route and shell → Service worker: registers