# shivakumart67/inventory-management architecture

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

- Interactive diagram: https://gitdiagram.com/shivakumart67/inventory-management
- Repository: https://github.com/shivakumart67/inventory-management

## Overview

#### Purpose and entry points
This is a TypeScript business-operations system for managing users, purchases, sales, expenses, inventory, activity logs, dashboards, and reports. It has separate backend API and frontend SPA applications.
- Backend process entry: `backend/src/server.ts`
- Frontend browser entry and application composition: `frontend/src/main.tsx`, `frontend/src/App.tsx`
- API surface is centrally registered in `backend/src/routes/api.ts`

#### Backend API and request boundary
The backend is a Node/TypeScript HTTP service organized as routes → middleware → controllers → models/services. Controllers expose domain endpoints for authentication, users, stock, transactions, reporting, dashboard metrics, activities, and site configuration.
- Routing: `backend/src/routes/api.ts`
- Request protection: `backend/src/middleware/auth.ts`
- Global failure boundary: `backend/src/middleware/errorHandler.ts`
- Representative endpoint handlers: `backend/src/controllers/authController.ts`, `backend/src/controllers/transactionController.ts`, `backend/src/controllers/reportController.ts`

#### Identity, roles, and application access
Authentication is enforced at the API boundary and reflected in the frontend’s protected-page flow. User administration and role-specific dashboards imply distinct operational access levels, including admin and manager views.
- Backend identity model and controller: `backend/src/models/User.ts`, `backend/src/controllers/userController.ts`
- Frontend auth state and route guard: `frontend/src/context/AuthContext.tsx`, `frontend/src/components/Protected.tsx`
- Role-oriented views: `frontend/src/pages/Dashboard/AdminDashboard.tsx`, `frontend/src/pages/Dashboard/ManagerDashboard.tsx`

#### Transaction-to-inventory flow
Purchases and sales are primary operational inputs. Stock is represented both as a movement ledger and an aggregated summary, with a dedicated stock service likely serving as the consistency boundary between transaction recording and inventory state.
- Transaction persistence: `backend/src/models/Purchase.ts`, `backend/src/models/Sale.ts`
- Inventory representations: `backend/src/models/StockLedger.ts`, `backend/src/models/StockSummary.ts`
- Inventory orchestration and API: `backend/src/services/stockService.ts`, `backend/src/controllers/stockController.ts`
- Corresponding workflows: `frontend/src/pages/Purchases/AddPurchase.tsx`, `frontend/src/pages/Sales/AddSale.tsx`, `frontend/src/pages/Stock/StockSummary.tsx`

#### Financial, reporting, and export flow
Expense capture, transaction data, and stock data feed dashboard and MIS/reporting endpoints. Reporting is separated from export/PDF generation, creating a boundary where operational data becomes downloadable or printable output.
- Expense domain: `backend/src/models/Expense.ts`, `backend/src/models/ExpenseCategory.ts`
- Dashboard/report APIs: `backend/src/controllers/dashboardController.ts`, `backend/src/controllers/reportController.ts`
- Output services: `backend/src/services/exportService.ts`, `backend/src/services/pdfService.ts`
- Reporting UI: `frontend/src/pages/Reports/ReportsDashboard.tsx`, `frontend/src/pages/Reports/MISDashboard.tsx`

#### Audit, configuration, and state management
Activity logging captures operational events as a cross-cutting audit capability. Site configuration is managed through its own API and frontend context. The backend has database configuration and a lightweight cache utility; persistence infrastructure details are not documented in the supplied README.
- Audit layer: `backend/src/models/ActivityLog.ts`, `backend/src/services/activityService.ts`
- Site settings: `backend/src/models/SiteConfig.ts`, `backend/src/controllers/siteConfigController.ts`, `frontend/src/context/SiteConfigContext.tsx`
- Infrastructure utilities: `backend/src/config/db.ts`, `backend/src/utils/simpleCache.ts`

#### Frontend integration boundary
The frontend is a Vite-based TypeScript SPA that uses a centralized API client, shared layout, contexts, and page-level domain workflows. It communicates with the backend rather than directly with persistence or report-generation services.
- API client: `frontend/src/services/api.ts`
- Shared shell and loading behavior: `frontend/src/components/Layout/AppLayout.tsx`, `frontend/src/components/GlobalLoader.tsx`
- Build/deployment indicators: `frontend/vite.config.ts`, `frontend/vercel.json`

Main entry points: [`frontend/src/services/api.ts`](https://github.com/shivakumart67/inventory-management/blob/main/frontend/src/services/api.ts) (Central API client), [`backend/src/routes/api.ts`](https://github.com/shivakumart67/inventory-management/blob/main/backend/src/routes/api.ts) (API route registry), [`backend/src/server.ts`](https://github.com/shivakumart67/inventory-management/blob/main/backend/src/server.ts) (Backend process), [`backend/src/middleware/auth.ts`](https://github.com/shivakumart67/inventory-management/blob/main/backend/src/middleware/auth.ts) (Authentication middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_web_entry["SPA entry &amp; composition<br/>React application"]
  node_web_access["Auth state &amp; page guard<br/>access control"]
  node_web_workflows["Purchase &amp; sale workflows<br/>domain pages"]
  node_web_stock["Stock summary view<br/>inventory page<br/>[StockSummary.tsx]"]
  node_web_reporting["Reports &amp; MIS views<br/>reporting pages"]
  node_web_admin["Admin &amp; manager dashboards<br/>role views"]
  node_web_config["Site configuration state<br/>frontend context"]
  node_api_client["Central API client<br/>HTTP client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_server["Backend process<br/>Node HTTP service<br/>[server.ts]"]
  node_routes["API route registry<br/>route boundary<br/>[api.ts]"]
  node_auth["Authentication middleware<br/>request protection<br/>[auth.ts]"]
  node_controllers["Domain controllers<br/>endpoint handlers"]
  node_error_handler["Global error handler<br/>failure boundary<br/>[errorHandler.ts]"]
end

subgraph group_operations["Operations &amp; Reporting"]
  node_stock_service["Stock consistency service<br/>inventory orchestration<br/>[stockService.ts]"]
  node_transactions[("Purchases &amp; sales<br/>transaction models")]
  node_inventory[("Stock ledger &amp; summary<br/>inventory models")]
  node_financial[("Expenses<br/>financial models")]
  node_report_output["Export &amp; PDF generation<br/>output services"]
end

subgraph group_persistence["Persistence &amp; Support"]
  node_identity[("Users &amp; roles<br/>identity model")]
  node_audit[("Activity audit log<br/>audit service")]
  node_site_config[("Site configuration<br/>configuration domain")]
  node_data_support[("Database &amp; cache<br/>infrastructure utilities")]
end

node_web_entry -->|"applies access flow"| node_web_access
node_web_entry -->|"uses"| node_api_client
node_web_workflows -->|"submits transactions"| node_api_client
node_web_stock -->|"reads stock"| node_api_client
node_web_reporting -->|"requests reports"| node_api_client
node_web_admin -->|"requests metrics"| node_api_client
node_web_config -->|"manages settings"| node_api_client
node_api_client -->|"HTTP requests"| node_server
node_server -->|"registers"| node_routes
node_routes -->|"protects requests"| node_auth
node_auth -->|"authorizes"| node_controllers
node_routes -.->|"routes failures to"| node_error_handler
node_controllers -->|"authenticates and manages users"| node_identity
node_controllers -->|"records purchases and sales"| node_transactions
node_controllers -->|"invokes inventory updates"| node_stock_service
node_stock_service -->|"writes movements and summaries"| node_inventory
node_controllers -->|"captures expenses"| node_financial
node_controllers -->|"generates exports"| node_report_output
node_controllers -->|"manages settings"| node_site_config
node_controllers -.->|"records activity"| node_audit
node_transactions -->|"persists through"| node_data_support
node_inventory -->|"persists through"| node_data_support
node_financial -->|"persists through"| node_data_support
node_identity -->|"persists through"| node_data_support
node_audit -->|"persists through"| node_data_support
node_site_config -->|"persists through"| node_data_support

click node_web_stock "https://github.com/shivakumart67/inventory-management/blob/main/frontend/src/pages/Stock/StockSummary.tsx"
click node_web_config "https://github.com/shivakumart67/inventory-management/blob/main/frontend/src/context/SiteConfigContext.tsx"
click node_api_client "https://github.com/shivakumart67/inventory-management/blob/main/frontend/src/services/api.ts"
click node_server "https://github.com/shivakumart67/inventory-management/blob/main/backend/src/server.ts"
click node_routes "https://github.com/shivakumart67/inventory-management/blob/main/backend/src/routes/api.ts"
click node_auth "https://github.com/shivakumart67/inventory-management/blob/main/backend/src/middleware/auth.ts"
click node_stock_service "https://github.com/shivakumart67/inventory-management/blob/main/backend/src/services/stockService.ts"
click node_error_handler "https://github.com/shivakumart67/inventory-management/blob/main/backend/src/middleware/errorHandler.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_entry,node_web_access,node_web_workflows,node_web_stock,node_web_reporting,node_web_admin,node_web_config,node_api_client toneBlue
class node_server,node_routes,node_auth,node_controllers,node_error_handler toneAmber
class node_stock_service,node_transactions,node_inventory,node_financial,node_report_output toneMint
class node_identity,node_audit,node_site_config,node_data_support toneRose
```

## Components

### Frontend SPA

- **SPA entry & composition**: React application
- **Auth state & page guard**: access control
- **Purchase & sale workflows**: domain pages
- [Stock summary view](https://github.com/shivakumart67/inventory-management/blob/main/frontend/src/pages/Stock/StockSummary.tsx): inventory page · `frontend/src/pages/Stock/StockSummary.tsx`
- **Reports & MIS views**: reporting pages
- **Admin & manager dashboards**: role views
- [Site configuration state](https://github.com/shivakumart67/inventory-management/blob/main/frontend/src/context/SiteConfigContext.tsx): frontend context · `frontend/src/context/SiteConfigContext.tsx`
- [Central API client](https://github.com/shivakumart67/inventory-management/blob/main/frontend/src/services/api.ts): HTTP client · `frontend/src/services/api.ts`

### Backend API

- [Backend process](https://github.com/shivakumart67/inventory-management/blob/main/backend/src/server.ts): Node HTTP service · `backend/src/server.ts`
- [API route registry](https://github.com/shivakumart67/inventory-management/blob/main/backend/src/routes/api.ts): route boundary · `backend/src/routes/api.ts`
- [Authentication middleware](https://github.com/shivakumart67/inventory-management/blob/main/backend/src/middleware/auth.ts): request protection · `backend/src/middleware/auth.ts`
- **Domain controllers**: endpoint handlers · Auth, user, transaction, stock, dashboard, report, and configuration endpoints.
- [Global error handler](https://github.com/shivakumart67/inventory-management/blob/main/backend/src/middleware/errorHandler.ts): failure boundary · `backend/src/middleware/errorHandler.ts`

### Operations & Reporting

- [Stock consistency service](https://github.com/shivakumart67/inventory-management/blob/main/backend/src/services/stockService.ts): inventory orchestration · Maintains inventory from transaction activity. · `backend/src/services/stockService.ts`
- **Purchases & sales**: transaction models
- **Stock ledger & summary**: inventory models · Movement ledger plus aggregated stock state.
- **Expenses**: financial models
- **Export & PDF generation**: output services

### Persistence & Support

- **Users & roles**: identity model
- **Activity audit log**: audit service
- **Site configuration**: configuration domain
- **Database & cache**: infrastructure utilities

## Connections

- SPA entry & composition → Auth state & page guard: applies access flow
- SPA entry & composition → Central API client: uses
- Purchase & sale workflows → Central API client: submits transactions
- Stock summary view → Central API client: reads stock
- Reports & MIS views → Central API client: requests reports
- Admin & manager dashboards → Central API client: requests metrics
- Site configuration state → Central API client: manages settings
- Central API client → Backend process: HTTP requests
- Backend process → API route registry: registers
- API route registry → Authentication middleware: protects requests
- Authentication middleware → Domain controllers: authorizes
- API route registry → Global error handler: routes failures to
- Domain controllers → Users & roles: authenticates and manages users
- Domain controllers → Purchases & sales: records purchases and sales
- Domain controllers → Stock consistency service: invokes inventory updates
- Stock consistency service → Stock ledger & summary: writes movements and summaries
- Domain controllers → Expenses: captures expenses
- Domain controllers → Export & PDF generation: generates exports
- Domain controllers → Site configuration: manages settings
- Domain controllers → Activity audit log: records activity
- Purchases & sales → Database & cache: persists through
- Stock ledger & summary → Database & cache: persists through
- Expenses → Database & cache: persists through
- Users & roles → Database & cache: persists through
- Activity audit log → Database & cache: persists through
- Site configuration → Database & cache: persists through