# shrikant-dapke/shelfsense architecture

> Architecture diagram of the GitHub repository shrikant-dapke/shelfsense, 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/shrikant-dapke/shelfsense
- Repository: https://github.com/shrikant-dapke/shelfsense

## Overview

ShelfSense is a perishable-goods inventory application built from a Next.js client and an Express/Prisma REST API. Users sign in, manage products and warehouses, receive and dispatch batch-tracked goods, and inspect ledger-derived inventory; stock counts and CSV/XLSX imports provide controlled adjustment and onboarding flows. The README describes an immutable movement ledger and audit logging. The graph includes documented product capabilities, but unsampled service internals and client-to-API calls are not inferred from filenames; those connections are omitted or marked unverified.

Main entry points: [`server/src/app.ts`](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/app.ts) (REST application), [`server/src/modules/auth/auth.service.ts`](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/auth/auth.service.ts) (Session and roles), [`server/src/modules/inventory/inventory.service.ts`](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/inventory/inventory.service.ts) (Ledger inventory), [`server/src/middleware/auth.middleware.ts`](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/middleware/auth.middleware.ts) (Authentication middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Inventory workspace<br/>[page.tsx]"]
  node_receipts_ui["Receiving UI<br/>[page.tsx]"]
  node_dispatch_ui["Dispatch UI<br/>[page.tsx]"]
  node_counts_ui["Stock count UI<br/>[page.tsx]"]
  node_imports_ui["Import UI<br/>[page.tsx]"]
  node_catalog_ui["Catalog UI<br/>[page.tsx]"]
  node_auth_ui["Sign-in UI<br/>[page.tsx]"]
  node_api_client["API client<br/>[api-client.ts]"]
end

subgraph group_api["API runtime"]
  node_api["REST application<br/>[app.ts]"]
  node_auth["Session and roles<br/>[auth.service.ts]"]
end

subgraph group_operations["Stock operations"]
  node_inventory["Ledger inventory"]
  node_receipts["Goods receipts"]
  node_dispatches["Stock dispatches"]
  node_batches["Batches and aliases<br/>[batches.service.ts]"]
  node_stockcounts["Count lifecycle"]
end

subgraph group_catalog["Catalog and imports"]
  node_products["Product catalog"]
  node_warehouses["Warehouses"]
  node_imports["File import workflow<br/>[imports.service.ts]"]
end

subgraph group_internals["Shared internals"]
  node_database[("PostgreSQL data<br/>[prisma.ts]")]
  node_authmw["Authentication middleware<br/>[auth.middleware.ts]"]
  node_validation["Request validation"]
  node_response["Response envelopes<br/>[api-response.ts]"]
  node_pagination["Pagination helpers<br/>[pagination.ts]"]
  node_jwt["JWT utilities<br/>[jwt.ts]"]
  node_audit["Audit logging<br/>[audit.service.ts]"]
  node_error["Error handling"]
end

node_user(("Staff user"))

node_user -->|"signs in"| node_auth_ui
node_user -->|"uses"| node_web
node_web -.->|"requests via"| node_api_client
node_api_client -->|"proxies API"| node_api
node_api -->|"mounts routes"| node_auth
node_api -->|"mounts routes"| node_products
node_api -->|"mounts routes"| node_warehouses
node_api -->|"mounts routes"| node_inventory
node_api -->|"mounts routes"| node_receipts
node_api -->|"mounts routes"| node_dispatches
node_api -->|"mounts routes"| node_batches
node_api -->|"mounts routes"| node_stockcounts
node_api -->|"mounts routes"| node_imports
node_auth -->|"reads users"| node_database
node_auth -->|"signs sessions"| node_jwt
node_auth -->|"records login"| node_audit
node_authmw -->|"verifies token"| node_jwt
node_authmw -->|"rechecks user"| node_database
node_validation -->|"raises validation errors"| node_error
node_imports -->|"supports upload preview"| node_imports_ui
node_stockcounts -->|"posts adjustments"| node_inventory
node_receipts -->|"writes receipt movements"| node_inventory
node_dispatches -->|"writes dispatch movements"| node_inventory

click node_web "https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/app/(app)/inventory/page.tsx"
click node_receipts_ui "https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/app/(app)/receipts/page.tsx"
click node_dispatch_ui "https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/app/(app)/dispatch/page.tsx"
click node_counts_ui "https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/app/(app)/stock-counts/page.tsx"
click node_imports_ui "https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/app/(app)/imports/page.tsx"
click node_catalog_ui "https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/app/(app)/products/page.tsx"
click node_auth_ui "https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/app/login/page.tsx"
click node_api_client "https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/lib/api-client.ts"
click node_api "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/app.ts"
click node_auth "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/auth/auth.service.ts"
click node_inventory "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/inventory/inventory.service.ts"
click node_receipts "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/receipts/receipts.service.ts"
click node_dispatches "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/dispatches/dispatches.service.ts"
click node_batches "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/batches/batches.service.ts"
click node_stockcounts "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/stockcounts/stockcounts.service.ts"
click node_products "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/products/products.controller.ts"
click node_warehouses "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/warehouses/warehouses.routes.ts"
click node_imports "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/imports/imports.service.ts"
click node_database "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/config/prisma.ts"
click node_authmw "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/middleware/auth.middleware.ts"
click node_validation "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/middleware/validate.middleware.ts"
click node_response "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/utils/api-response.ts"
click node_pagination "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/utils/pagination.ts"
click node_jwt "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/utils/jwt.ts"
click node_audit "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/services/audit.service.ts"
click node_error "https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/middleware/error.middleware.ts"

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_web,node_receipts_ui,node_dispatch_ui,node_counts_ui,node_imports_ui,node_catalog_ui,node_auth_ui,node_api_client,node_user toneBlue
class node_api,node_auth toneAmber
class node_inventory,node_receipts,node_dispatches,node_batches,node_stockcounts toneMint
class node_products,node_warehouses,node_imports toneRose
class node_database,node_authmw,node_validation,node_response,node_pagination,node_jwt,node_audit,node_error toneIndigo
```

## Components

### Web client

- [Inventory workspace](https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/app/(app)/inventory/page.tsx): `client/src/app/(app)/inventory/page.tsx`
- [Receiving UI](https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/app/(app)/receipts/page.tsx): `client/src/app/(app)/receipts/page.tsx`
- [Dispatch UI](https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/app/(app)/dispatch/page.tsx): `client/src/app/(app)/dispatch/page.tsx`
- [Stock count UI](https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/app/(app)/stock-counts/page.tsx): `client/src/app/(app)/stock-counts/page.tsx`
- [Import UI](https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/app/(app)/imports/page.tsx): `client/src/app/(app)/imports/page.tsx`
- [Catalog UI](https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/app/(app)/products/page.tsx): `client/src/app/(app)/products/page.tsx`
- [Sign-in UI](https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/app/login/page.tsx): `client/src/app/login/page.tsx`
- [API client](https://github.com/shrikant-dapke/shelfsense/blob/main/client/src/lib/api-client.ts): `client/src/lib/api-client.ts`

### API runtime

- [REST application](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/app.ts): `server/src/app.ts`
- [Session and roles](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/auth/auth.service.ts): `server/src/modules/auth/auth.service.ts`

### Stock operations

- [Ledger inventory](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/inventory/inventory.service.ts): `server/src/modules/inventory/inventory.service.ts`
- [Goods receipts](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/receipts/receipts.service.ts): `server/src/modules/receipts/receipts.service.ts`
- [Stock dispatches](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/dispatches/dispatches.service.ts): `server/src/modules/dispatches/dispatches.service.ts`
- [Batches and aliases](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/batches/batches.service.ts): `server/src/modules/batches/batches.service.ts`
- [Count lifecycle](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/stockcounts/stockcounts.service.ts): `server/src/modules/stockcounts/stockcounts.service.ts`

### Catalog and imports

- [Product catalog](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/products/products.controller.ts): `server/src/modules/products/products.controller.ts`
- [Warehouses](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/warehouses/warehouses.routes.ts): `server/src/modules/warehouses/warehouses.routes.ts`
- [File import workflow](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/modules/imports/imports.service.ts): `server/src/modules/imports/imports.service.ts`

### Shared internals

- [PostgreSQL data](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/config/prisma.ts): `server/src/config/prisma.ts`
- [Authentication middleware](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/middleware/auth.middleware.ts): `server/src/middleware/auth.middleware.ts`
- [Request validation](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/middleware/validate.middleware.ts): `server/src/middleware/validate.middleware.ts`
- [Response envelopes](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/utils/api-response.ts): `server/src/utils/api-response.ts`
- [Pagination helpers](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/utils/pagination.ts): `server/src/utils/pagination.ts`
- [JWT utilities](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/utils/jwt.ts): `server/src/utils/jwt.ts`
- [Audit logging](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/services/audit.service.ts): `server/src/services/audit.service.ts`
- [Error handling](https://github.com/shrikant-dapke/shelfsense/blob/main/server/src/middleware/error.middleware.ts): `server/src/middleware/error.middleware.ts`

### Other components

- **Staff user**

## Connections

- Staff user → Sign-in UI: signs in (evidence: `README.md`)
- Staff user → Inventory workspace: uses (evidence: `README.md`)
- Inventory workspace → API client: requests via
- API client → REST application: proxies API (evidence: `README.md`)
- REST application → Session and roles: mounts routes (evidence: `server/src/app.ts`)
- REST application → Product catalog: mounts routes (evidence: `server/src/app.ts`)
- REST application → Warehouses: mounts routes (evidence: `server/src/app.ts`)
- REST application → Ledger inventory: mounts routes (evidence: `server/src/app.ts`)
- REST application → Goods receipts: mounts routes (evidence: `server/src/app.ts`)
- REST application → Stock dispatches: mounts routes (evidence: `server/src/app.ts`)
- REST application → Batches and aliases: mounts routes (evidence: `server/src/app.ts`)
- REST application → Count lifecycle: mounts routes (evidence: `server/src/app.ts`)
- REST application → File import workflow: mounts routes (evidence: `server/src/app.ts`)
- Session and roles → PostgreSQL data: reads users (evidence: `server/src/modules/auth/auth.service.ts`)
- Session and roles → JWT utilities: signs sessions (evidence: `server/src/modules/auth/auth.service.ts`)
- Session and roles → Audit logging: records login (evidence: `server/src/modules/auth/auth.service.ts`)
- Authentication middleware → JWT utilities: verifies token (evidence: `server/src/middleware/auth.middleware.ts`)
- Authentication middleware → PostgreSQL data: rechecks user (evidence: `server/src/middleware/auth.middleware.ts`)
- Request validation → Error handling: raises validation errors (evidence: `server/src/middleware/validate.middleware.ts`)
- File import workflow → Import UI: supports upload preview (evidence: `README.md`)
- Count lifecycle → Ledger inventory: posts adjustments (evidence: `README.md`)
- Goods receipts → Ledger inventory: writes receipt movements (evidence: `README.md`)
- Stock dispatches → Ledger inventory: writes dispatch movements (evidence: `README.md`)