# afiroj313501/stockpilot architecture

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

## Overview

StockPilot AI is a retail inventory and point-of-sale platform. Staff use its web application to manage products, stock, purchasing, sales and returns; managers and owners also access reports, reorder recommendations and an assistant. The API applies session, store and role checks before domain routes call services, with Prisma as the persistence layer. The README is brief and the sampled source is selective, so web-to-API calls and unsampled service internals are not mapped; documented route-to-service relationships are shown where the index or excerpts support them.

Main entry points: [`apps/api/src/app.ts`](https://github.com/afiroj313501/stockpilot/blob/main/apps/api/src/app.ts) (API application), [`apps/web/src/App.tsx`](https://github.com/afiroj313501/stockpilot/blob/main/apps/web/src/App.tsx) (Web routes), [`apps/api/src/modules/auth/auth.service.ts`](https://github.com/afiroj313501/stockpilot/blob/main/apps/api/src/modules/auth/auth.service.ts) (Account and sessions), [`apps/api/src/modules/purchases`](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/purchases) (Purchasing and receiving)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Web routes<br/>[App.tsx]"]
  node_webops["Operations screens"]
  node_webinsights["Insights screens"]
end

subgraph group_access["Access and platform"]
  node_apiserver["API application<br/>[app.ts]"]
  node_authroutes["Authentication routes<br/>[auth.routes.ts]"]
  node_authmiddleware["Session middleware<br/>[auth.middleware.ts]"]
  node_authservice["Account and sessions<br/>[auth.service.ts]"]
  node_storeaccess["Store and role checks"]
  node_database[("Prisma data access<br/>[prisma.ts]")]
  node_users["Store users"]
  node_miscapi["Store and health endpoints"]
end

subgraph group_operations["Retail operations"]
  node_catalog["Catalog management"]
  node_inventory["Stock management"]
  node_purchasing["Purchasing and receiving"]
  node_sales["POS and sales"]
  node_returns["Returns and refunds"]
  node_suppliers["Supplier management"]
  node_categories["Category management"]
  node_settings["Store settings"]
end

subgraph group_insights["Insights and assistance"]
  node_forecasting["Reorder forecasting"]
  node_reports["Reports and exports"]
  node_audit["Audit history"]
  node_assistant["AI assistant"]
end

node_staff(("Retail staff"))

node_staff -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_webops
node_webapp -->|"routes to"| node_webinsights
node_apiserver -->|"mounts"| node_authroutes
node_apiserver -->|"mounts"| node_catalog
node_apiserver -->|"mounts"| node_inventory
node_apiserver -->|"mounts"| node_purchasing
node_apiserver -->|"mounts"| node_sales
node_apiserver -->|"mounts"| node_returns
node_apiserver -.->|"mounts"| node_forecasting
node_apiserver -.->|"mounts"| node_reports
node_apiserver -.->|"mounts"| node_audit
node_apiserver -.->|"mounts"| node_assistant
node_apiserver -->|"mounts"| node_suppliers
node_apiserver -->|"mounts"| node_categories
node_apiserver -->|"mounts"| node_settings
node_apiserver -->|"mounts"| node_users
node_apiserver -->|"mounts"| node_miscapi
node_authroutes -.->|"handles accounts"| node_authservice
node_authmiddleware -->|"resolves sessions"| node_authservice
node_authservice -->|"reads and writes"| node_database
node_purchasing -.->|"creates draft orders"| node_forecasting
node_forecasting -->|"approves to draft"| node_purchasing
node_reports -->|"builds exports"| node_reports

click node_webapp "https://github.com/afiroj313501/stockpilot/blob/main/apps/web/src/App.tsx"
click node_webops "https://github.com/afiroj313501/stockpilot/tree/main/apps/web/src/pages"
click node_webinsights "https://github.com/afiroj313501/stockpilot/tree/main/apps/web/src/pages"
click node_apiserver "https://github.com/afiroj313501/stockpilot/blob/main/apps/api/src/app.ts"
click node_authroutes "https://github.com/afiroj313501/stockpilot/blob/main/apps/api/src/modules/auth/auth.routes.ts"
click node_authmiddleware "https://github.com/afiroj313501/stockpilot/blob/main/apps/api/src/modules/auth/auth.middleware.ts"
click node_authservice "https://github.com/afiroj313501/stockpilot/blob/main/apps/api/src/modules/auth/auth.service.ts"
click node_storeaccess "https://github.com/afiroj313501/stockpilot/blob/main/apps/api/src/modules/auth/store.middleware.ts"
click node_database "https://github.com/afiroj313501/stockpilot/blob/main/apps/api/src/db/prisma.ts"
click node_catalog "https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/products"
click node_inventory "https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/inventory"
click node_purchasing "https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/purchases"
click node_sales "https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/sales"
click node_returns "https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/returns"
click node_forecasting "https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/forecasting"
click node_reports "https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/reports"
click node_audit "https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/audit"
click node_assistant "https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/ai"
click node_suppliers "https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/suppliers"
click node_categories "https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/categories"
click node_settings "https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/settings"
click node_users "https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/users"
click node_miscapi "https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/stores"

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_webapp,node_webops,node_webinsights toneBlue
class node_apiserver,node_authroutes,node_authmiddleware,node_authservice,node_storeaccess,node_database,node_users,node_miscapi toneAmber
class node_catalog,node_inventory,node_purchasing,node_sales,node_returns,node_suppliers,node_categories,node_settings toneMint
class node_forecasting,node_reports,node_audit,node_assistant toneRose
class node_staff toneIndigo
```

## Components

### Web application

- [Web routes](https://github.com/afiroj313501/stockpilot/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Operations screens](https://github.com/afiroj313501/stockpilot/tree/main/apps/web/src/pages): `apps/web/src/pages`
- [Insights screens](https://github.com/afiroj313501/stockpilot/tree/main/apps/web/src/pages): `apps/web/src/pages`

### Access and platform

- [API application](https://github.com/afiroj313501/stockpilot/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Authentication routes](https://github.com/afiroj313501/stockpilot/blob/main/apps/api/src/modules/auth/auth.routes.ts): `apps/api/src/modules/auth/auth.routes.ts`
- [Session middleware](https://github.com/afiroj313501/stockpilot/blob/main/apps/api/src/modules/auth/auth.middleware.ts): `apps/api/src/modules/auth/auth.middleware.ts`
- [Account and sessions](https://github.com/afiroj313501/stockpilot/blob/main/apps/api/src/modules/auth/auth.service.ts): `apps/api/src/modules/auth/auth.service.ts`
- [Store and role checks](https://github.com/afiroj313501/stockpilot/blob/main/apps/api/src/modules/auth/store.middleware.ts): `apps/api/src/modules/auth/store.middleware.ts`
- [Prisma data access](https://github.com/afiroj313501/stockpilot/blob/main/apps/api/src/db/prisma.ts): `apps/api/src/db/prisma.ts`
- [Store users](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/users): `apps/api/src/modules/users`
- [Store and health endpoints](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/stores): `apps/api/src/modules/stores`

### Retail operations

- [Catalog management](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/products): `apps/api/src/modules/products`
- [Stock management](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/inventory): `apps/api/src/modules/inventory`
- [Purchasing and receiving](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/purchases): `apps/api/src/modules/purchases`
- [POS and sales](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/sales): `apps/api/src/modules/sales`
- [Returns and refunds](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/returns): `apps/api/src/modules/returns`
- [Supplier management](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/suppliers): `apps/api/src/modules/suppliers`
- [Category management](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/categories): `apps/api/src/modules/categories`
- [Store settings](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/settings): `apps/api/src/modules/settings`

### Insights and assistance

- [Reorder forecasting](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/forecasting): `apps/api/src/modules/forecasting`
- [Reports and exports](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/reports): `apps/api/src/modules/reports`
- [Audit history](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/audit): `apps/api/src/modules/audit`
- [AI assistant](https://github.com/afiroj313501/stockpilot/tree/main/apps/api/src/modules/ai): `apps/api/src/modules/ai`

### Other components

- **Retail staff**

## Connections

- Retail staff → Web routes: uses
- Web routes → Operations screens: routes to (evidence: `apps/web/src/App.tsx`)
- Web routes → Insights screens: routes to (evidence: `apps/web/src/App.tsx`)
- API application → Authentication routes: mounts (evidence: `apps/api/src/app.ts`)
- API application → Catalog management: mounts (evidence: `apps/api/src/app.ts`)
- API application → Stock management: mounts (evidence: `apps/api/src/app.ts`)
- API application → Purchasing and receiving: mounts (evidence: `apps/api/src/app.ts`)
- API application → POS and sales: mounts (evidence: `apps/api/src/app.ts`)
- API application → Returns and refunds: mounts (evidence: `apps/api/src/app.ts`)
- API application → Reorder forecasting: mounts (evidence: `apps/api/src/app.ts`)
- API application → Reports and exports: mounts (evidence: `apps/api/src/app.ts`)
- API application → Audit history: mounts (evidence: `apps/api/src/app.ts`)
- API application → AI assistant: mounts (evidence: `apps/api/src/app.ts`)
- API application → Supplier management: mounts (evidence: `apps/api/src/app.ts`)
- API application → Category management: mounts (evidence: `apps/api/src/app.ts`)
- API application → Store settings: mounts (evidence: `apps/api/src/app.ts`)
- API application → Store users: mounts (evidence: `apps/api/src/app.ts`)
- API application → Store and health endpoints: mounts (evidence: `apps/api/src/app.ts`)
- Authentication routes → Account and sessions: handles accounts (evidence: `apps/api/src/modules/auth/auth.routes.ts`)
- Session middleware → Account and sessions: resolves sessions (evidence: `apps/api/src/modules/auth/auth.middleware.ts`)
- Account and sessions → Prisma data access: reads and writes (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Purchasing and receiving → Reorder forecasting: creates draft orders
- Reorder forecasting → Purchasing and receiving: approves to draft (evidence: `apps/api/src/modules/forecasting/forecasting.routes.ts`)
- Reports and exports → Reports and exports: builds exports (evidence: `apps/api/src/modules/reports/reports.routes.ts`)