# kanisk-sk/supply-chain architecture

> Architecture diagram of the GitHub repository kanisk-sk/supply-chain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kanisk-sk/supply-chain
- Repository: https://github.com/kanisk-sk/supply-chain

## Overview

This is a supply-chain tracking and analytics application: users manage master data and inventory, place and advance orders, dispatch and track shipments, and inspect alerts and live analytics. The backend’s FastAPI entry point registers the product routers; domain services own transactional rules and delegate persistence to repositories, with state machines governing order and shipment lifecycles. The tree also shows corresponding Next.js screens and shared API utilities. The README is empty, and most frontend wiring and several routers were not sampled, so those connections are not asserted here.

Main entry points: [`backend/app/main.py`](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/modules/shipments/service.py`](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/shipments/service.py) (Shipment lifecycle), [`backend/app/modules/inventory/service.py`](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/inventory/service.py) (Inventory control), [`backend/app/modules/products/service.py`](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/products/service.py) (Product catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_database[("SQL database<br/>[database.py]")]
end

subgraph group_operations["Supply-chain operations"]
  node_auth["Authentication"]
  node_users["User management<br/>[service.py]"]
  node_products["Product catalog<br/>[service.py]"]
  node_suppliers["Supplier management<br/>[service.py]"]
  node_warehouses["Warehouse management"]
  node_inventory["Inventory control<br/>[service.py]"]
  node_orders["Order lifecycle<br/>[service.py]"]
  node_order_states["Order state machine<br/>[order.py]"]
  node_shipments["Shipment lifecycle<br/>[service.py]"]
  node_shipment_states["Shipment state machine<br/>[shipment.py]"]
  node_tracking["Public tracking<br/>[public_router.py]"]
end

subgraph group_insight["Operational insight"]
  node_scheduler["Alert scheduler<br/>[service.py]"]
  node_alerts["Derived alerts<br/>[service.py]"]
  node_analytics["Live analytics<br/>[service.py]"]
  node_audit["Audit history<br/>[service.py]"]
end

subgraph group_web["Web experience"]
  node_web_api["Web API client<br/>[api.ts]"]
  node_web_auth["Login and access<br/>[page.tsx]"]
  node_web_inventory["Inventory screen<br/>[page.tsx]"]
  node_web_orders["Order screens<br/>[page.tsx]"]
  node_web_shipments["Shipment screens<br/>[page.tsx]"]
  node_web_tracking["Tracking screens<br/>[page.tsx]"]
  node_web_analytics["Analytics screen<br/>[page.tsx]"]
  node_web_alerts["Alerts screen<br/>[page.tsx]"]
  node_web_products["Product screen<br/>[page.tsx]"]
  node_web_suppliers["Supplier screen<br/>[page.tsx]"]
  node_web_warehouses["Warehouse screen<br/>[page.tsx]"]
  node_web_users["Admin users<br/>[page.tsx]"]
end

node_api_app -->|"registers routes"| node_auth
node_api_app -->|"registers routes"| node_users
node_api_app -->|"registers routes"| node_products
node_api_app -->|"registers routes"| node_suppliers
node_api_app -->|"registers routes"| node_warehouses
node_api_app -->|"registers routes"| node_inventory
node_api_app -->|"registers routes"| node_orders
node_api_app -->|"registers routes"| node_shipments
node_api_app -->|"registers routes"| node_tracking
node_api_app -->|"registers routes"| node_alerts
node_api_app -->|"registers routes"| node_analytics
node_api_app -->|"starts optionally"| node_scheduler
node_users -->|"uses ORM models"| node_database
node_products -->|"reads supplier data"| node_suppliers
node_products -->|"reconciles stock alerts"| node_alerts
node_products -->|"records changes"| node_audit
node_inventory -->|"reads product data"| node_products
node_inventory -->|"reads warehouse data"| node_warehouses
node_inventory -->|"reconciles alerts"| node_alerts
node_inventory -->|"records changes"| node_audit
node_orders -->|"validates products"| node_products
node_orders -->|"validates transitions"| node_order_states
node_orders -->|"records changes"| node_audit
node_shipments -->|"dispatches stock"| node_inventory
node_shipments -->|"reads order data"| node_orders
node_shipments -->|"validates transitions"| node_shipment_states
node_shipments -->|"reconciles overdue"| node_alerts
node_shipments -->|"records changes"| node_audit
node_tracking -.->|"serves public view"| node_shipments
node_scheduler -->|"reconciles overdue"| node_alerts
node_scheduler -->|"queries candidates"| node_database
node_analytics -->|"queries metrics"| node_database
node_web_inventory -.->|"uses API client"| node_web_api
node_web_orders -.->|"uses API client"| node_web_api
node_web_shipments -.->|"uses API client"| node_web_api
node_web_tracking -.->|"uses API client"| node_web_api
node_web_analytics -.->|"uses API client"| node_web_api
node_web_alerts -.->|"uses API client"| node_web_api

click node_api_app "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/main.py"
click node_database "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/core/database.py"
click node_scheduler "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/jobs/service.py"
click node_auth "https://github.com/kanisk-sk/supply-chain/tree/main/backend/app/modules/auth"
click node_users "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/users/service.py"
click node_products "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/products/service.py"
click node_suppliers "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/suppliers/service.py"
click node_warehouses "https://github.com/kanisk-sk/supply-chain/tree/main/backend/app/modules/warehouses"
click node_inventory "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/inventory/service.py"
click node_orders "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/orders/service.py"
click node_order_states "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/state_machines/order.py"
click node_shipments "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/shipments/service.py"
click node_shipment_states "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/state_machines/shipment.py"
click node_tracking "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/shipments/public_router.py"
click node_alerts "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/alerts/service.py"
click node_analytics "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/analytics/service.py"
click node_audit "https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/audit_logs/service.py"
click node_web_api "https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/lib/api.ts"
click node_web_auth "https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/login/page.tsx"
click node_web_inventory "https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/inventory/page.tsx"
click node_web_orders "https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/orders/page.tsx"
click node_web_shipments "https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/shipments/page.tsx"
click node_web_tracking "https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/tracking/%5BtrackingNumber%5D/page.tsx"
click node_web_analytics "https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/analytics/page.tsx"
click node_web_alerts "https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/alerts/page.tsx"
click node_web_products "https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/products/page.tsx"
click node_web_suppliers "https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/suppliers/page.tsx"
click node_web_warehouses "https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/warehouses/page.tsx"
click node_web_users "https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/admin/users/page.tsx"

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_api_app,node_database toneBlue
class node_auth,node_users,node_products,node_suppliers,node_warehouses,node_inventory,node_orders,node_order_states,node_shipments,node_shipment_states,node_tracking toneAmber
class node_scheduler,node_alerts,node_analytics,node_audit toneMint
class node_web_api,node_web_auth,node_web_inventory,node_web_orders,node_web_shipments,node_web_tracking,node_web_analytics,node_web_alerts,node_web_products,node_web_suppliers,node_web_warehouses,node_web_users toneRose
```

## Components

### Application entry

- [FastAPI application](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/main.py): `backend/app/main.py`
- [SQL database](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Supply-chain operations

- [Authentication](https://github.com/kanisk-sk/supply-chain/tree/main/backend/app/modules/auth): `backend/app/modules/auth`
- [User management](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/users/service.py): `backend/app/modules/users/service.py`
- [Product catalog](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/products/service.py): `backend/app/modules/products/service.py`
- [Supplier management](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/suppliers/service.py): `backend/app/modules/suppliers/service.py`
- [Warehouse management](https://github.com/kanisk-sk/supply-chain/tree/main/backend/app/modules/warehouses): `backend/app/modules/warehouses`
- [Inventory control](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/inventory/service.py): `backend/app/modules/inventory/service.py`
- [Order lifecycle](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/orders/service.py): `backend/app/modules/orders/service.py`
- [Order state machine](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/state_machines/order.py): `backend/app/state_machines/order.py`
- [Shipment lifecycle](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/shipments/service.py): `backend/app/modules/shipments/service.py`
- [Shipment state machine](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/state_machines/shipment.py): `backend/app/state_machines/shipment.py`
- [Public tracking](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/shipments/public_router.py): `backend/app/modules/shipments/public_router.py`

### Operational insight

- [Alert scheduler](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/jobs/service.py): `backend/app/jobs/service.py`
- [Derived alerts](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/alerts/service.py): `backend/app/modules/alerts/service.py`
- [Live analytics](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/analytics/service.py): `backend/app/modules/analytics/service.py`
- [Audit history](https://github.com/kanisk-sk/supply-chain/blob/main/backend/app/modules/audit_logs/service.py): `backend/app/modules/audit_logs/service.py`

### Web experience

- [Web API client](https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Login and access](https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/login/page.tsx): `frontend/src/app/login/page.tsx`
- [Inventory screen](https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/inventory/page.tsx): `frontend/src/app/inventory/page.tsx`
- [Order screens](https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/orders/page.tsx): `frontend/src/app/orders/page.tsx`
- [Shipment screens](https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/shipments/page.tsx): `frontend/src/app/shipments/page.tsx`
- [Tracking screens](https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/tracking/%5BtrackingNumber%5D/page.tsx): `frontend/src/app/tracking/[trackingNumber]/page.tsx`
- [Analytics screen](https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/analytics/page.tsx): `frontend/src/app/analytics/page.tsx`
- [Alerts screen](https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/alerts/page.tsx): `frontend/src/app/alerts/page.tsx`
- [Product screen](https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/products/page.tsx): `frontend/src/app/products/page.tsx`
- [Supplier screen](https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/suppliers/page.tsx): `frontend/src/app/suppliers/page.tsx`
- [Warehouse screen](https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/warehouses/page.tsx): `frontend/src/app/warehouses/page.tsx`
- [Admin users](https://github.com/kanisk-sk/supply-chain/blob/main/frontend/src/app/admin/users/page.tsx): `frontend/src/app/admin/users/page.tsx`

## Connections

- FastAPI application → Authentication: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → User management: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Product catalog: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Supplier management: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Warehouse management: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Inventory control: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Order lifecycle: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Shipment lifecycle: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Public tracking: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Derived alerts: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Live analytics: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Alert scheduler: starts optionally (evidence: `backend/app/main.py`)
- User management → SQL database: uses ORM models
- Product catalog → Supplier management: reads supplier data (evidence: `backend/app/modules/products/service.py`)
- Product catalog → Derived alerts: reconciles stock alerts (evidence: `backend/app/modules/products/service.py`)
- Product catalog → Audit history: records changes (evidence: `backend/app/modules/products/service.py`)
- Inventory control → Product catalog: reads product data (evidence: `backend/app/modules/inventory/service.py`)
- Inventory control → Warehouse management: reads warehouse data (evidence: `backend/app/modules/inventory/service.py`)
- Inventory control → Derived alerts: reconciles alerts (evidence: `backend/app/modules/inventory/service.py`)
- Inventory control → Audit history: records changes (evidence: `backend/app/modules/inventory/service.py`)
- Order lifecycle → Product catalog: validates products (evidence: `backend/app/modules/orders/service.py`)
- Order lifecycle → Order state machine: validates transitions (evidence: `backend/app/modules/orders/service.py`)
- Order lifecycle → Audit history: records changes (evidence: `backend/app/modules/orders/service.py`)
- Shipment lifecycle → Inventory control: dispatches stock (evidence: `backend/app/modules/shipments/service.py`)
- Shipment lifecycle → Order lifecycle: reads order data (evidence: `backend/app/modules/shipments/service.py`)
- Shipment lifecycle → Shipment state machine: validates transitions (evidence: `backend/app/modules/shipments/service.py`)
- Shipment lifecycle → Derived alerts: reconciles overdue (evidence: `backend/app/modules/shipments/service.py`)
- Shipment lifecycle → Audit history: records changes (evidence: `backend/app/modules/shipments/service.py`)
- Public tracking → Shipment lifecycle: serves public view
- Alert scheduler → Derived alerts: reconciles overdue (evidence: `backend/app/jobs/service.py`)
- Alert scheduler → SQL database: queries candidates (evidence: `backend/app/jobs/service.py`)
- Live analytics → SQL database: queries metrics (evidence: `backend/app/modules/analytics/service.py`)
- Inventory screen → Web API client: uses API client
- Order screens → Web API client: uses API client
- Shipment screens → Web API client: uses API client
- Tracking screens → Web API client: uses API client
- Analytics screen → Web API client: uses API client
- Alerts screen → Web API client: uses API client
