# monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system architecture

> Architecture diagram of the GitHub repository monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system
- Repository: https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system

## Overview

OptiStock is an inventory intelligence product for small businesses. Users authenticate, enter or import stock and sales data, then review inventory, forecasts, recommendations, supplier information, and agent activity through the React dashboard. The frontend calls a FastAPI REST service backed by SQLite. The backend also coordinates specialized agents for monitoring, anomalies, procurement, pricing, supplier scoring, alerts, and reporting. The README documents these capabilities; several backend implementations and routes were not sampled, so only documented or indexed relationships are shown.

Main entry points: [`optistock/src/api.py`](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/api.py) (REST API), [`optistock/src/agents/orchestrator.py`](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/orchestrator.py) (Agent orchestrator), [`optistock/frontend/src/services/api.js`](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/services/api.js) (API client), [`optistock/frontend/src/App.jsx`](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/App.jsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_app_shell["App shell<br/>[App.jsx]"]
  node_auth_ui["Session state<br/>[AuthContext.jsx]"]
  node_inventory_ui["Inventory views<br/>[Inventory.jsx]"]
  node_dashboard_ui["Business dashboard<br/>[Dashboard.jsx]"]
  node_analysis_ui["Analysis views<br/>[Analysis.jsx]"]
  node_agent_ui["Agent hub<br/>[AgentHub.jsx]"]
  node_sales_ui["Sales entry<br/>[SalesEntry.jsx]"]
  node_supplier_ui["Supplier views<br/>[Suppliers.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_backend["API and intelligence"]
  node_fastapi["REST API<br/>[api.py]"]
  node_auth_logic["Authentication<br/>[auth.py]"]
  node_forecast["Hybrid forecasting"]
  node_optimizer["Stock optimization"]
  node_nl_query["Natural language queries<br/>[nl_query_engine.py]"]
  node_ai_advice["AI advice<br/>[agent_logic.py]"]
  node_supplier_score["Supplier scoring"]
end

subgraph group_agents["Agent system"]
  node_orchestrator["Agent orchestrator<br/>[orchestrator.py]"]
  node_agent_base["Agent runtime<br/>[base_agent.py]"]
  node_monitor_agent["Inventory monitor"]
  node_anomaly_agent["Anomaly detection"]
  node_procurement_agent["Auto procurement"]
  node_pricing_agent["Dynamic pricing"]
  node_supplier_agent["Supplier intelligence"]
  node_alert_agent["Alert notifications"]
  node_report_agent["Scheduled reports"]
end

subgraph group_data["Persistence"]
  node_sqlite[("SQLite database<br/>[database.py]")]
end

node_shop_manager(("Shop manager"))
node_gemini{{"Google Gemini"}}

node_shop_manager -->|"uses"| node_app_shell
node_app_shell -->|"provides session"| node_auth_ui
node_app_shell -->|"routes to"| node_dashboard_ui
node_app_shell -->|"routes to"| node_inventory_ui
node_app_shell -->|"routes to"| node_analysis_ui
node_app_shell -->|"routes to"| node_agent_ui
node_inventory_ui -->|"requests inventory"| node_api_client
node_dashboard_ui -->|"requests inventory"| node_api_client
node_analysis_ui -->|"requests analysis"| node_api_client
node_agent_ui -->|"controls agents"| node_api_client
node_sales_ui -->|"submits sales"| node_api_client
node_supplier_ui -->|"requests suppliers"| node_api_client
node_auth_ui -->|"validates token"| node_fastapi
node_api_client -->|"calls REST endpoints"| node_fastapi
node_fastapi -.->|"authenticates requests"| node_auth_logic
node_auth_logic -->|"looks up users"| node_sqlite
node_fastapi -->|"persists business data"| node_sqlite
node_fastapi -->|"forecasts demand"| node_forecast
node_fastapi -->|"calculates reorder levels"| node_optimizer
node_fastapi -->|"handles natural-language queries"| node_nl_query
node_fastapi -->|"generates business advice"| node_ai_advice
node_fastapi -->|"scores suppliers"| node_supplier_score
node_ai_advice -->|"requests language generation"| node_gemini
node_orchestrator -->|"runs"| node_monitor_agent
node_orchestrator -->|"runs"| node_anomaly_agent
node_orchestrator -->|"runs"| node_procurement_agent
node_orchestrator -->|"coordinates"| node_pricing_agent
node_orchestrator -->|"coordinates"| node_supplier_agent
node_orchestrator -->|"coordinates"| node_alert_agent
node_orchestrator -->|"coordinates"| node_report_agent
node_monitor_agent -->|"inherits runtime"| node_agent_base
node_anomaly_agent -->|"inherits runtime"| node_agent_base
node_procurement_agent -->|"inherits runtime"| node_agent_base
node_alert_agent -->|"inherits runtime"| node_agent_base
node_report_agent -->|"inherits runtime"| node_agent_base
node_procurement_agent -->|"uses predictions"| node_forecast
node_procurement_agent -->|"calculates replenishment"| node_optimizer
node_monitor_agent -->|"checks stock thresholds"| node_optimizer
node_alert_agent -->|"records alerts"| node_sqlite
node_report_agent -->|"reads business records"| node_sqlite

click node_app_shell "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/App.jsx"
click node_auth_ui "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/context/AuthContext.jsx"
click node_inventory_ui "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/pages/Inventory.jsx"
click node_dashboard_ui "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/pages/Dashboard.jsx"
click node_analysis_ui "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/pages/Analysis.jsx"
click node_agent_ui "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/pages/AgentHub.jsx"
click node_sales_ui "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/pages/SalesEntry.jsx"
click node_supplier_ui "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/pages/Suppliers.jsx"
click node_api_client "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/services/api.js"
click node_fastapi "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/api.py"
click node_auth_logic "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/auth.py"
click node_forecast "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/advanced_forecasting.py"
click node_optimizer "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/inventory_optimizer.py"
click node_nl_query "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/nl_query_engine.py"
click node_ai_advice "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agent_logic.py"
click node_supplier_score "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/supplier_scoring.py"
click node_orchestrator "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/orchestrator.py"
click node_agent_base "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/base_agent.py"
click node_monitor_agent "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/inventory_monitor_agent.py"
click node_anomaly_agent "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/anomaly_detection_agent.py"
click node_procurement_agent "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/auto_procurement_agent.py"
click node_pricing_agent "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/dynamic_pricing_agent.py"
click node_supplier_agent "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/supplier_intelligence_agent.py"
click node_alert_agent "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/alert_notification_agent.py"
click node_report_agent "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/scheduled_reporting_agent.py"
click node_sqlite "https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/database.py"

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_shell,node_auth_ui,node_inventory_ui,node_dashboard_ui,node_analysis_ui,node_agent_ui,node_sales_ui,node_supplier_ui,node_api_client toneBlue
class node_fastapi,node_auth_logic,node_forecast,node_optimizer,node_nl_query,node_ai_advice,node_supplier_score toneAmber
class node_orchestrator,node_agent_base,node_monitor_agent,node_anomaly_agent,node_procurement_agent,node_pricing_agent,node_supplier_agent,node_alert_agent,node_report_agent toneMint
class node_sqlite toneRose
class node_shop_manager,node_gemini toneIndigo
```

## Components

### Dashboard

- [App shell](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/App.jsx): `optistock/frontend/src/App.jsx`
- [Session state](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/context/AuthContext.jsx): `optistock/frontend/src/context/AuthContext.jsx`
- [Inventory views](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/pages/Inventory.jsx): `optistock/frontend/src/pages/Inventory.jsx`
- [Business dashboard](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/pages/Dashboard.jsx): `optistock/frontend/src/pages/Dashboard.jsx`
- [Analysis views](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/pages/Analysis.jsx): `optistock/frontend/src/pages/Analysis.jsx`
- [Agent hub](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/pages/AgentHub.jsx): `optistock/frontend/src/pages/AgentHub.jsx`
- [Sales entry](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/pages/SalesEntry.jsx): `optistock/frontend/src/pages/SalesEntry.jsx`
- [Supplier views](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/pages/Suppliers.jsx): `optistock/frontend/src/pages/Suppliers.jsx`
- [API client](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/frontend/src/services/api.js): `optistock/frontend/src/services/api.js`

### API and intelligence

- [REST API](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/api.py): `optistock/src/api.py`
- [Authentication](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/auth.py): `optistock/src/auth.py`
- [Hybrid forecasting](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/advanced_forecasting.py): `optistock/src/advanced_forecasting.py`
- [Stock optimization](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/inventory_optimizer.py): `optistock/src/inventory_optimizer.py`
- [Natural language queries](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/nl_query_engine.py): `optistock/src/nl_query_engine.py`
- [AI advice](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agent_logic.py): `optistock/src/agent_logic.py`
- [Supplier scoring](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/supplier_scoring.py): `optistock/src/supplier_scoring.py`

### Agent system

- [Agent orchestrator](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/orchestrator.py): `optistock/src/agents/orchestrator.py`
- [Agent runtime](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/base_agent.py): `optistock/src/agents/base_agent.py`
- [Inventory monitor](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/inventory_monitor_agent.py): `optistock/src/agents/inventory_monitor_agent.py`
- [Anomaly detection](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/anomaly_detection_agent.py): `optistock/src/agents/anomaly_detection_agent.py`
- [Auto procurement](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/auto_procurement_agent.py): `optistock/src/agents/auto_procurement_agent.py`
- [Dynamic pricing](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/dynamic_pricing_agent.py): `optistock/src/agents/dynamic_pricing_agent.py`
- [Supplier intelligence](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/supplier_intelligence_agent.py): `optistock/src/agents/supplier_intelligence_agent.py`
- [Alert notifications](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/alert_notification_agent.py): `optistock/src/agents/alert_notification_agent.py`
- [Scheduled reports](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/agents/scheduled_reporting_agent.py): `optistock/src/agents/scheduled_reporting_agent.py`

### Persistence

- [SQLite database](https://github.com/monishp-eng/optistock-ai-an-autonomous-multi-agent-inventory-intelligence-demand-forecasting-system/blob/main/optistock/src/database.py): `optistock/src/database.py`

### Other components

- **Shop manager**
- **Google Gemini**

## Connections

- Shop manager → App shell: uses
- App shell → Session state: provides session (evidence: `optistock/frontend/src/App.jsx`)
- App shell → Business dashboard: routes to (evidence: `optistock/frontend/src/App.jsx`)
- App shell → Inventory views: routes to (evidence: `optistock/frontend/src/App.jsx`)
- App shell → Analysis views: routes to (evidence: `optistock/frontend/src/App.jsx`)
- App shell → Agent hub: routes to (evidence: `optistock/frontend/src/App.jsx`)
- Inventory views → API client: requests inventory (evidence: `optistock/frontend/src/pages/Inventory.jsx`)
- Business dashboard → API client: requests inventory (evidence: `optistock/frontend/src/pages/Dashboard.jsx`)
- Analysis views → API client: requests analysis (evidence: `optistock/frontend/src/pages/Analysis.jsx`)
- Agent hub → API client: controls agents (evidence: `optistock/frontend/src/pages/AgentHub.jsx`)
- Sales entry → API client: submits sales
- Supplier views → API client: requests suppliers (evidence: `optistock/frontend/src/pages/Suppliers.jsx`)
- Session state → REST API: validates token (evidence: `optistock/frontend/src/context/AuthContext.jsx`)
- API client → REST API: calls REST endpoints
- REST API → Authentication: authenticates requests
- Authentication → SQLite database: looks up users (evidence: `optistock/src/auth.py`)
- REST API → SQLite database: persists business data
- REST API → Hybrid forecasting: forecasts demand
- REST API → Stock optimization: calculates reorder levels
- REST API → Natural language queries: handles natural-language queries
- REST API → AI advice: generates business advice
- REST API → Supplier scoring: scores suppliers
- AI advice → Google Gemini: requests language generation
- Agent orchestrator → Inventory monitor: runs (evidence: `optistock/src/agents/orchestrator.py`)
- Agent orchestrator → Anomaly detection: runs (evidence: `optistock/src/agents/orchestrator.py`)
- Agent orchestrator → Auto procurement: runs (evidence: `optistock/src/agents/orchestrator.py`)
- Agent orchestrator → Dynamic pricing: coordinates (evidence: `optistock/src/agents/orchestrator.py`)
- Agent orchestrator → Supplier intelligence: coordinates (evidence: `optistock/src/agents/orchestrator.py`)
- Agent orchestrator → Alert notifications: coordinates (evidence: `optistock/src/agents/orchestrator.py`)
- Agent orchestrator → Scheduled reports: coordinates (evidence: `optistock/src/agents/orchestrator.py`)
- Inventory monitor → Agent runtime: inherits runtime (evidence: `optistock/src/agents/inventory_monitor_agent.py`)
- Anomaly detection → Agent runtime: inherits runtime
- Auto procurement → Agent runtime: inherits runtime (evidence: `optistock/src/agents/auto_procurement_agent.py`)
- Alert notifications → Agent runtime: inherits runtime (evidence: `optistock/src/agents/alert_notification_agent.py`)
- Scheduled reports → Agent runtime: inherits runtime (evidence: `optistock/src/agents/scheduled_reporting_agent.py`)
- Auto procurement → Hybrid forecasting: uses predictions (evidence: `optistock/src/agents/auto_procurement_agent.py`)
- Auto procurement → Stock optimization: calculates replenishment (evidence: `optistock/src/agents/auto_procurement_agent.py`)
- Inventory monitor → Stock optimization: checks stock thresholds (evidence: `optistock/src/agents/inventory_monitor_agent.py`)
- Alert notifications → SQLite database: records alerts (evidence: `optistock/src/agents/alert_notification_agent.py`)
- Scheduled reports → SQLite database: reads business records (evidence: `optistock/src/agents/scheduled_reporting_agent.py`)
