# akilanpl/stocksense architecture

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

- Interactive diagram: https://gitdiagram.com/akilanpl/stocksense
- Repository: https://github.com/akilanpl/stocksense

## Overview

StockSense is a web-based inventory operations workspace. Staff manage catalog and warehouse structure, record receipts, deliveries, transfers, and adjustments, then validate operations that affect stock and the auditable movement history. The README documents dashboard health and authentication capabilities. The graph follows the sampled API-to-service calls; deeper wiring for unsampled features is shown only where documented, with no inferred call sequence between operation types.

Main entry points: [`src/lib/api`](https://github.com/akilanpl/stocksense/tree/main/src/lib/api) (Browser API client), [`src/server/db/prisma.ts`](https://github.com/akilanpl/stocksense/blob/main/src/server/db/prisma.ts) (Prisma access), [`src/app/api/auth`](https://github.com/akilanpl/stocksense/tree/main/src/app/api/auth) (Auth routes), [`src/app/(app)`](https://github.com/akilanpl/stocksense/tree/main/src/app/(app)) (Workspace pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Workspace UI"]
  node_workspace["Workspace pages"]
  node_authui["Auth pages"]
  node_apiclient["Browser API client"]
end

subgraph group_api["REST API"]
  node_catalogroutes["Catalog routes<br/>[route.ts]"]
  node_operationroutes["Operation routes<br/>[route.ts]"]
  node_stockroutes["Stock &amp; moves routes<br/>[route.ts]"]
  node_dashboardroute["Dashboard route<br/>[route.ts]"]
  node_authroutes["Auth routes"]
end

subgraph group_domain["Inventory Services"]
  node_catalog["Product &amp; site catalog"]
  node_operations["Operation lifecycle<br/>[operations.ts]"]
  node_inventory["Stock ledger &amp; queries"]
  node_dashboard["Inventory health<br/>[dashboard.ts]"]
end

subgraph group_identity["Identity Services"]
  node_auth["Accounts &amp; sessions"]
  node_verification["Email verification<br/>[verification.ts]"]
  node_mailer["Mail delivery<br/>[mailer.ts]"]
end

subgraph group_persistence["Persistence &amp; Email"]
  node_database[("PostgreSQL")]
  node_prisma["Prisma access<br/>[prisma.ts]"]
end

node_staff(("Inventory staff"))
node_smtp["SMTP service"]

node_staff -->|"uses"| node_workspace
node_staff -->|"signs in"| node_authui
node_workspace -->|"requests data"| node_apiclient
node_authui -->|"submits credentials"| node_apiclient
node_apiclient -->|"calls"| node_catalogroutes
node_apiclient -->|"calls"| node_operationroutes
node_apiclient -->|"calls"| node_stockroutes
node_apiclient -->|"calls"| node_dashboardroute
node_apiclient -->|"calls"| node_authroutes
node_catalogroutes -->|"invokes"| node_catalog
node_operationroutes -->|"invokes"| node_operations
node_stockroutes -->|"queries"| node_inventory
node_dashboardroute -->|"queries"| node_dashboard
node_authroutes -->|"invokes"| node_auth
node_authroutes -->|"starts verification"| node_verification
node_verification -->|"sends email"| node_mailer
node_mailer -->|"delivers"| node_smtp
node_catalog -->|"persists records"| node_prisma
node_operations -->|"reads and writes"| node_prisma
node_inventory -->|"reads ledger"| node_prisma
node_dashboard -->|"reads metrics"| node_prisma
node_auth -->|"stores accounts"| node_prisma
node_prisma -->|"queries"| node_database

click node_workspace "https://github.com/akilanpl/stocksense/tree/main/src/app/(app)"
click node_authui "https://github.com/akilanpl/stocksense/tree/main/src/app/(auth)"
click node_apiclient "https://github.com/akilanpl/stocksense/tree/main/src/lib/api"
click node_catalogroutes "https://github.com/akilanpl/stocksense/blob/main/src/app/api/products/route.ts"
click node_operationroutes "https://github.com/akilanpl/stocksense/blob/main/src/app/api/operations/route.ts"
click node_stockroutes "https://github.com/akilanpl/stocksense/blob/main/src/app/api/stock/route.ts"
click node_dashboardroute "https://github.com/akilanpl/stocksense/blob/main/src/app/api/dashboard/route.ts"
click node_authroutes "https://github.com/akilanpl/stocksense/tree/main/src/app/api/auth"
click node_catalog "https://github.com/akilanpl/stocksense/tree/main/src/server/catalog"
click node_operations "https://github.com/akilanpl/stocksense/blob/main/src/server/operations/operations.ts"
click node_inventory "https://github.com/akilanpl/stocksense/tree/main/src/server/inventory"
click node_dashboard "https://github.com/akilanpl/stocksense/blob/main/src/server/inventory/dashboard.ts"
click node_auth "https://github.com/akilanpl/stocksense/tree/main/src/server/auth"
click node_verification "https://github.com/akilanpl/stocksense/blob/main/src/server/auth/verification.ts"
click node_mailer "https://github.com/akilanpl/stocksense/blob/main/src/server/email/mailer.ts"
click node_prisma "https://github.com/akilanpl/stocksense/blob/main/src/server/db/prisma.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_workspace,node_authui,node_apiclient toneBlue
class node_catalogroutes,node_operationroutes,node_stockroutes,node_dashboardroute,node_authroutes toneAmber
class node_catalog,node_operations,node_inventory,node_dashboard toneMint
class node_auth,node_verification,node_mailer toneRose
class node_database,node_prisma,node_staff,node_smtp toneIndigo
```

## Components

### Workspace UI

- [Workspace pages](https://github.com/akilanpl/stocksense/tree/main/src/app/(app)): `src/app/(app)`
- [Auth pages](https://github.com/akilanpl/stocksense/tree/main/src/app/(auth)): `src/app/(auth)`
- [Browser API client](https://github.com/akilanpl/stocksense/tree/main/src/lib/api): `src/lib/api`

### REST API

- [Catalog routes](https://github.com/akilanpl/stocksense/blob/main/src/app/api/products/route.ts): `src/app/api/products/route.ts`
- [Operation routes](https://github.com/akilanpl/stocksense/blob/main/src/app/api/operations/route.ts): `src/app/api/operations/route.ts`
- [Stock & moves routes](https://github.com/akilanpl/stocksense/blob/main/src/app/api/stock/route.ts): `src/app/api/stock/route.ts`
- [Dashboard route](https://github.com/akilanpl/stocksense/blob/main/src/app/api/dashboard/route.ts): `src/app/api/dashboard/route.ts`
- [Auth routes](https://github.com/akilanpl/stocksense/tree/main/src/app/api/auth): `src/app/api/auth`

### Inventory Services

- [Product & site catalog](https://github.com/akilanpl/stocksense/tree/main/src/server/catalog): `src/server/catalog`
- [Operation lifecycle](https://github.com/akilanpl/stocksense/blob/main/src/server/operations/operations.ts): `src/server/operations/operations.ts`
- [Stock ledger & queries](https://github.com/akilanpl/stocksense/tree/main/src/server/inventory): `src/server/inventory`
- [Inventory health](https://github.com/akilanpl/stocksense/blob/main/src/server/inventory/dashboard.ts): `src/server/inventory/dashboard.ts`

### Identity Services

- [Accounts & sessions](https://github.com/akilanpl/stocksense/tree/main/src/server/auth): `src/server/auth`
- [Email verification](https://github.com/akilanpl/stocksense/blob/main/src/server/auth/verification.ts): `src/server/auth/verification.ts`
- [Mail delivery](https://github.com/akilanpl/stocksense/blob/main/src/server/email/mailer.ts): `src/server/email/mailer.ts`

### Persistence & Email

- **PostgreSQL**
- [Prisma access](https://github.com/akilanpl/stocksense/blob/main/src/server/db/prisma.ts): `src/server/db/prisma.ts`

### Other components

- **Inventory staff**
- **SMTP service**

## Connections

- Inventory staff → Workspace pages: uses
- Inventory staff → Auth pages: signs in
- Workspace pages → Browser API client: requests data
- Auth pages → Browser API client: submits credentials
- Browser API client → Catalog routes: calls
- Browser API client → Operation routes: calls
- Browser API client → Stock & moves routes: calls
- Browser API client → Dashboard route: calls
- Browser API client → Auth routes: calls
- Catalog routes → Product & site catalog: invokes
- Operation routes → Operation lifecycle: invokes
- Stock & moves routes → Stock ledger & queries: queries
- Dashboard route → Inventory health: queries
- Auth routes → Accounts & sessions: invokes
- Auth routes → Email verification: starts verification
- Email verification → Mail delivery: sends email
- Mail delivery → SMTP service: delivers
- Product & site catalog → Prisma access: persists records
- Operation lifecycle → Prisma access: reads and writes
- Stock ledger & queries → Prisma access: reads ledger
- Inventory health → Prisma access: reads metrics
- Accounts & sessions → Prisma access: stores accounts
- Prisma access → PostgreSQL: queries