# ryfless/sparetrack architecture

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

- Interactive diagram: https://gitdiagram.com/ryfless/sparetrack
- Repository: https://github.com/ryfless/sparetrack

## Overview

SpareTrack is a multi-branch spare-parts inventory system. A user enters through the React application, authenticates, and uses its operational pages; frontend API services send requests to Express, whose routes and controllers delegate inventory, transactions, reporting, and restock work to services backed by Supabase. In parallel, the ML service builds demand features from Supabase data, trains XGBoost, and serves forecasts used for restock recommendations. The README documents additional product capabilities; only relationships visible in excerpts or the README are drawn, so some subsystem connections remain unverified.

Main entry points: [`backend/src/config/supabase.js`](https://github.com/ryfless/sparetrack/blob/main/backend/src/config/supabase.js) (Supabase client), [`inventory_ml/api.py`](https://github.com/ryfless/sparetrack/blob/main/inventory_ml/api.py) (Forecast API), [`inventory_ml/main.py`](https://github.com/ryfless/sparetrack/blob/main/inventory_ml/main.py) (ML runtime), [`frontend/src/app/App.tsx`](https://github.com/ryfless/sparetrack/blob/main/frontend/src/app/App.tsx) (React application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["React application<br/>[App.tsx]"]
  node_authpages["Auth pages"]
  node_operationalpages["Operational pages"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_backend["REST backend"]
  node_backend_app["Express API<br/>[app.js]"]
  node_api_routes["API routes<br/>[index.js]"]
  node_auth_controller["Auth controller<br/>[authController.js]"]
  node_auth_service["Auth service<br/>[authService.js]"]
  node_inventory_controller["Inventory controller"]
  node_restock_controller["Restock controller"]
  node_supabase_js["Supabase client<br/>[supabase.js]"]
end

subgraph group_domain["Inventory operations"]
  node_inventory_service["Inventory service"]
  node_restock_service["Restock and PO service<br/>[restockService.js]"]
  node_reporting["Reports service<br/>[reportsService.js]"]
  node_transactions["Transaction services"]
  node_notifications["Notifications"]
end

subgraph group_ml["Demand forecasting"]
  node_ml_data["Demand data features<br/>[data.py]"]
  node_ml_model["XGBoost model<br/>[xgboost.py]"]
  node_ml_api["Forecast API<br/>[api.py]"]
  node_ml_runtime["ML runtime<br/>[main.py]"]
  node_ml_dashboard["ML dashboard<br/>[app.js]"]
end

node_user(("Store user"))
node_database[("Supabase database")]

node_user -->|"uses"| node_app
node_app -->|"presents"| node_authpages
node_app -->|"routes to"| node_operationalpages
node_authpages -.->|"requests"| node_api_client
node_operationalpages -.->|"requests"| node_api_client
node_app -->|"updates theme"| node_api_client
node_api_client -->|"REST requests"| node_backend_app
node_backend_app -->|"mounts"| node_api_routes
node_api_routes -.->|"routes auth"| node_auth_controller
node_api_routes -.->|"routes inventory"| node_inventory_controller
node_api_routes -.->|"routes restock"| node_restock_controller
node_backend_app -->|"handles profile"| node_auth_controller
node_auth_controller -->|"delegates auth"| node_auth_service
node_auth_service -->|"reads and writes"| node_supabase_js
node_inventory_controller -->|"delegates inventory"| node_inventory_service
node_restock_controller -->|"delegates restock"| node_restock_service
node_inventory_service -->|"reads and writes"| node_supabase_js
node_restock_service -->|"reads and writes"| node_supabase_js
node_inventory_service -->|"triggers"| node_notifications
node_restock_service -->|"triggers"| node_notifications
node_reporting -->|"queries data"| node_supabase_js
node_transactions -.->|"persists records"| node_supabase_js
node_supabase_js -->|"accesses"| node_database
node_ml_runtime -->|"fetches features"| node_ml_data
node_ml_runtime -->|"trains model"| node_ml_model
node_ml_runtime -->|"starts service"| node_ml_api
node_ml_data -->|"loads history"| node_database
node_ml_api -->|"builds forecasts"| node_ml_data
node_ml_api -->|"predicts demand"| node_ml_model
node_ml_api -.->|"stores forecasts"| node_database
node_ml_runtime -.->|"serves dashboard"| node_ml_dashboard
node_ml_api -.->|"forecast integration"| node_restock_service

click node_app "https://github.com/ryfless/sparetrack/blob/main/frontend/src/app/App.tsx"
click node_authpages "https://github.com/ryfless/sparetrack/tree/main/frontend/src/app/pages/auth"
click node_operationalpages "https://github.com/ryfless/sparetrack/tree/main/frontend/src/app/pages/app"
click node_api_client "https://github.com/ryfless/sparetrack/blob/main/frontend/src/app/services/client.ts"
click node_backend_app "https://github.com/ryfless/sparetrack/blob/main/backend/src/app.js"
click node_api_routes "https://github.com/ryfless/sparetrack/blob/main/backend/src/routes/index.js"
click node_auth_controller "https://github.com/ryfless/sparetrack/blob/main/backend/src/controllers/authController.js"
click node_auth_service "https://github.com/ryfless/sparetrack/blob/main/backend/src/services/authService.js"
click node_inventory_controller "https://github.com/ryfless/sparetrack/blob/main/backend/src/controllers/inventoryController.js"
click node_restock_controller "https://github.com/ryfless/sparetrack/blob/main/backend/src/controllers/restockController.js"
click node_inventory_service "https://github.com/ryfless/sparetrack/blob/main/backend/src/services/inventoryService.js"
click node_restock_service "https://github.com/ryfless/sparetrack/blob/main/backend/src/services/restockService.js"
click node_reporting "https://github.com/ryfless/sparetrack/blob/main/backend/src/services/reportsService.js"
click node_transactions "https://github.com/ryfless/sparetrack/blob/main/backend/src/services/transactionsService.js"
click node_notifications "https://github.com/ryfless/sparetrack/blob/main/backend/src/services/notificationService.js"
click node_supabase_js "https://github.com/ryfless/sparetrack/blob/main/backend/src/config/supabase.js"
click node_ml_data "https://github.com/ryfless/sparetrack/blob/main/inventory_ml/models/data.py"
click node_ml_model "https://github.com/ryfless/sparetrack/blob/main/inventory_ml/models/xgboost.py"
click node_ml_api "https://github.com/ryfless/sparetrack/blob/main/inventory_ml/api.py"
click node_ml_runtime "https://github.com/ryfless/sparetrack/blob/main/inventory_ml/main.py"
click node_ml_dashboard "https://github.com/ryfless/sparetrack/blob/main/inventory_ml/dashboard/app.js"

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_app,node_authpages,node_operationalpages,node_api_client,node_user toneBlue
class node_backend_app,node_api_routes,node_auth_controller,node_auth_service,node_inventory_controller,node_restock_controller,node_supabase_js,node_database toneAmber
class node_inventory_service,node_restock_service,node_reporting,node_transactions,node_notifications toneMint
class node_ml_data,node_ml_model,node_ml_api,node_ml_runtime,node_ml_dashboard toneRose
```

## Components

### Web application

- [React application](https://github.com/ryfless/sparetrack/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Auth pages](https://github.com/ryfless/sparetrack/tree/main/frontend/src/app/pages/auth): `frontend/src/app/pages/auth`
- [Operational pages](https://github.com/ryfless/sparetrack/tree/main/frontend/src/app/pages/app): `frontend/src/app/pages/app`
- [API client](https://github.com/ryfless/sparetrack/blob/main/frontend/src/app/services/client.ts): `frontend/src/app/services/client.ts`

### REST backend

- [Express API](https://github.com/ryfless/sparetrack/blob/main/backend/src/app.js): `backend/src/app.js`
- [API routes](https://github.com/ryfless/sparetrack/blob/main/backend/src/routes/index.js): `backend/src/routes/index.js`
- [Auth controller](https://github.com/ryfless/sparetrack/blob/main/backend/src/controllers/authController.js): `backend/src/controllers/authController.js`
- [Auth service](https://github.com/ryfless/sparetrack/blob/main/backend/src/services/authService.js): `backend/src/services/authService.js`
- [Inventory controller](https://github.com/ryfless/sparetrack/blob/main/backend/src/controllers/inventoryController.js): `backend/src/controllers/inventoryController.js`
- [Restock controller](https://github.com/ryfless/sparetrack/blob/main/backend/src/controllers/restockController.js): `backend/src/controllers/restockController.js`
- [Supabase client](https://github.com/ryfless/sparetrack/blob/main/backend/src/config/supabase.js): `backend/src/config/supabase.js`

### Inventory operations

- [Inventory service](https://github.com/ryfless/sparetrack/blob/main/backend/src/services/inventoryService.js): `backend/src/services/inventoryService.js`
- [Restock and PO service](https://github.com/ryfless/sparetrack/blob/main/backend/src/services/restockService.js): `backend/src/services/restockService.js`
- [Reports service](https://github.com/ryfless/sparetrack/blob/main/backend/src/services/reportsService.js): `backend/src/services/reportsService.js`
- [Transaction services](https://github.com/ryfless/sparetrack/blob/main/backend/src/services/transactionsService.js): `backend/src/services/transactionsService.js`
- [Notifications](https://github.com/ryfless/sparetrack/blob/main/backend/src/services/notificationService.js): `backend/src/services/notificationService.js`

### Demand forecasting

- [Demand data features](https://github.com/ryfless/sparetrack/blob/main/inventory_ml/models/data.py): `inventory_ml/models/data.py`
- [XGBoost model](https://github.com/ryfless/sparetrack/blob/main/inventory_ml/models/xgboost.py): `inventory_ml/models/xgboost.py`
- [Forecast API](https://github.com/ryfless/sparetrack/blob/main/inventory_ml/api.py): `inventory_ml/api.py`
- [ML runtime](https://github.com/ryfless/sparetrack/blob/main/inventory_ml/main.py): `inventory_ml/main.py`
- [ML dashboard](https://github.com/ryfless/sparetrack/blob/main/inventory_ml/dashboard/app.js): `inventory_ml/dashboard/app.js`

### Other components

- **Store user**
- **Supabase database**

## Connections

- Store user → React application: uses
- React application → Auth pages: presents (evidence: `frontend/src/app/App.tsx`)
- React application → Operational pages: routes to (evidence: `frontend/src/app/App.tsx`)
- Auth pages → API client: requests
- Operational pages → API client: requests
- React application → API client: updates theme (evidence: `frontend/src/app/App.tsx`)
- API client → Express API: REST requests
- Express API → API routes: mounts (evidence: `backend/src/app.js`)
- API routes → Auth controller: routes auth
- API routes → Inventory controller: routes inventory
- API routes → Restock controller: routes restock
- Express API → Auth controller: handles profile (evidence: `backend/src/app.js`)
- Auth controller → Auth service: delegates auth (evidence: `backend/src/controllers/authController.js`)
- Auth service → Supabase client: reads and writes (evidence: `backend/src/services/authService.js`)
- Inventory controller → Inventory service: delegates inventory (evidence: `backend/src/controllers/inventoryController.js`)
- Restock controller → Restock and PO service: delegates restock (evidence: `backend/src/controllers/restockController.js`)
- Inventory service → Supabase client: reads and writes (evidence: `backend/src/services/inventoryService.js`)
- Restock and PO service → Supabase client: reads and writes (evidence: `backend/src/services/restockService.js`)
- Inventory service → Notifications: triggers (evidence: `backend/src/services/inventoryService.js`)
- Restock and PO service → Notifications: triggers (evidence: `backend/src/services/restockService.js`)
- Reports service → Supabase client: queries data (evidence: `backend/src/services/reportsService.js`)
- Transaction services → Supabase client: persists records
- Supabase client → Supabase database: accesses (evidence: `backend/src/config/supabase.js`)
- ML runtime → Demand data features: fetches features (evidence: `inventory_ml/main.py`)
- ML runtime → XGBoost model: trains model (evidence: `inventory_ml/main.py`)
- ML runtime → Forecast API: starts service (evidence: `inventory_ml/main.py`)
- Demand data features → Supabase database: loads history (evidence: `inventory_ml/models/data.py`)
- Forecast API → Demand data features: builds forecasts (evidence: `inventory_ml/api.py`)
- Forecast API → XGBoost model: predicts demand (evidence: `inventory_ml/api.py`)
- Forecast API → Supabase database: stores forecasts
- ML runtime → ML dashboard: serves dashboard
- Forecast API → Restock and PO service: forecast integration
