# ahmadarif238/smart-supplychain-agent architecture

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

- Interactive diagram: https://gitdiagram.com/ahmadarif238/smart-supplychain-agent
- Repository: https://github.com/ahmadarif238/smart-supplychain-agent

## Overview

Smart Supply Chain Agent is a web application for coordinating inventory replenishment under demand and finance constraints. Managers use the React dashboard to inspect operations and launch an agent cycle; the API runs a stateful workflow that fetches supply-chain data, forecasts demand, optimizes reorder decisions, applies finance constraints, negotiates rejected proposals, and records purchase actions. The product also exposes operational views, feedback, and persistent agent memory. README documents the principal decision loop; unsampled route and UI details are represented only at their existing directory paths.

Main entry points: [`app/agents/langgraph_workflow.py`](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/langgraph_workflow.py) (Workflow orchestration), [`app/routes/agent.py`](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/routes/agent.py) (Agent endpoints), [`app/models/database.py`](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/models/database.py) (Application database), [`react-app/src/App.tsx`](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/react-app/src/App.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Manager interface"]
  node_web["Web application<br/>[App.tsx]"]
  node_agent_ui["Agent cycle views"]
  node_ops_ui["Operations views"]
end

subgraph group_api["API and operations"]
  node_api_entry["FastAPI application<br/>[main.py]"]
  node_agent_routes["Agent endpoints<br/>[agent.py]"]
  node_business_routes["Supply-chain endpoints"]
  node_auth["Authentication<br/>[dependencies.py]"]
  node_memory_routes["Memory endpoints<br/>[persistence.py]"]
end

subgraph group_agent["Agent workflow"]
  node_cycle["Workflow orchestration"]
  node_cycle_state["Cycle state<br/>[state.py]"]
  node_fetch["Data fetch<br/>[fetch_data_node.py]"]
  node_forecast["Demand forecast<br/>[forecast_node.py]"]
  node_decision["Order optimization"]
  node_finance["Budget review<br/>[finance_node.py]"]
  node_negotiation["Proposal negotiation<br/>[review_node.py]"]
  node_action["Purchase actions<br/>[action_node.py]"]
  node_stream["Progress streaming<br/>[streaming.py]"]
  node_llm["LLM service<br/>[llm_service.py]"]
end

subgraph group_data["State and persistence"]
  node_db[("Application database<br/>[database.py]")]
  node_memory["Persistent memory"]
end

node_manager(("Supply manager"))

node_manager -->|"uses"| node_web
node_web -->|"opens"| node_agent_ui
node_web -->|"opens"| node_ops_ui
node_agent_ui -.->|"requests cycle"| node_agent_routes
node_ops_ui -.->|"requests data"| node_business_routes
node_api_entry -->|"registers"| node_agent_routes
node_api_entry -->|"registers"| node_business_routes
node_agent_routes -->|"depends on"| node_auth
node_agent_routes -->|"invokes workflow"| node_cycle
node_cycle -->|"runs stage"| node_fetch
node_cycle -->|"runs stage"| node_forecast
node_cycle -->|"runs stage"| node_decision
node_cycle -->|"runs stage"| node_finance
node_cycle -.->|"reviews proposals"| node_negotiation
node_cycle -->|"runs stage"| node_action
node_cycle -->|"shares state"| node_cycle_state
node_fetch -->|"reads supply data"| node_db
node_forecast -.->|"uses model service"| node_llm
node_forecast -->|"emits progress"| node_stream
node_negotiation -->|"emits progress"| node_stream
node_action -->|"writes orders"| node_db
node_cycle -->|"saves run summary"| node_memory
node_business_routes -.->|"accesses records"| node_db
node_memory_routes -->|"accesses memory"| node_db
node_memory -->|"persists records"| node_db
node_agent_routes -->|"streams job updates"| node_stream

click node_web "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/react-app/src/App.tsx"
click node_agent_ui "https://github.com/ahmadarif238/smart-supplychain-agent/tree/main/react-app/src/pages"
click node_ops_ui "https://github.com/ahmadarif238/smart-supplychain-agent/tree/main/react-app/src/pages"
click node_api_entry "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/main.py"
click node_agent_routes "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/routes/agent.py"
click node_business_routes "https://github.com/ahmadarif238/smart-supplychain-agent/tree/main/app/routes"
click node_auth "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/auth/dependencies.py"
click node_cycle "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/langgraph_workflow.py"
click node_cycle_state "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/state.py"
click node_fetch "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/nodes/fetch_data_node.py"
click node_forecast "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/nodes/forecast_node.py"
click node_decision "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/nodes/intelligent_decision_node.py"
click node_finance "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/nodes/finance_node.py"
click node_negotiation "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/nodes/review_node.py"
click node_action "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/nodes/action_node.py"
click node_stream "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/streaming.py"
click node_llm "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/services/llm_service.py"
click node_db "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/models/database.py"
click node_memory "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/persistence/persistent_memory.py"
click node_memory_routes "https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/routes/persistence.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_web,node_agent_ui,node_ops_ui toneBlue
class node_api_entry,node_agent_routes,node_business_routes,node_auth,node_memory_routes toneAmber
class node_cycle,node_cycle_state,node_fetch,node_forecast,node_decision,node_finance,node_negotiation,node_action,node_stream,node_llm toneMint
class node_db,node_memory toneRose
class node_manager toneIndigo
```

## Components

### Manager interface

- [Web application](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/react-app/src/App.tsx): `react-app/src/App.tsx`
- [Agent cycle views](https://github.com/ahmadarif238/smart-supplychain-agent/tree/main/react-app/src/pages): `react-app/src/pages`
- [Operations views](https://github.com/ahmadarif238/smart-supplychain-agent/tree/main/react-app/src/pages): `react-app/src/pages`

### API and operations

- [FastAPI application](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/main.py): `main.py`
- [Agent endpoints](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/routes/agent.py): `app/routes/agent.py`
- [Supply-chain endpoints](https://github.com/ahmadarif238/smart-supplychain-agent/tree/main/app/routes): `app/routes`
- [Authentication](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/auth/dependencies.py): `app/auth/dependencies.py`
- [Memory endpoints](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/routes/persistence.py): `app/routes/persistence.py`

### Agent workflow

- [Workflow orchestration](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/langgraph_workflow.py): `app/agents/langgraph_workflow.py`
- [Cycle state](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/state.py): `app/agents/state.py`
- [Data fetch](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/nodes/fetch_data_node.py): `app/agents/nodes/fetch_data_node.py`
- [Demand forecast](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/nodes/forecast_node.py): `app/agents/nodes/forecast_node.py`
- [Order optimization](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/nodes/intelligent_decision_node.py): `app/agents/nodes/intelligent_decision_node.py`
- [Budget review](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/nodes/finance_node.py): `app/agents/nodes/finance_node.py`
- [Proposal negotiation](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/nodes/review_node.py): `app/agents/nodes/review_node.py`
- [Purchase actions](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/nodes/action_node.py): `app/agents/nodes/action_node.py`
- [Progress streaming](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/agents/streaming.py): `app/agents/streaming.py`
- [LLM service](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/services/llm_service.py): `app/services/llm_service.py`

### State and persistence

- [Application database](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/models/database.py): `app/models/database.py`
- [Persistent memory](https://github.com/ahmadarif238/smart-supplychain-agent/blob/main/app/persistence/persistent_memory.py): `app/persistence/persistent_memory.py`

### Other components

- **Supply manager**

## Connections

- Supply manager → Web application: uses (evidence: `react-app/src/App.tsx`)
- Web application → Agent cycle views: opens (evidence: `react-app/src/App.tsx`)
- Web application → Operations views: opens (evidence: `react-app/src/App.tsx`)
- Agent cycle views → Agent endpoints: requests cycle
- Operations views → Supply-chain endpoints: requests data
- FastAPI application → Agent endpoints: registers (evidence: `main.py`)
- FastAPI application → Supply-chain endpoints: registers (evidence: `main.py`)
- Agent endpoints → Authentication: depends on (evidence: `app/routes/agent.py`)
- Agent endpoints → Workflow orchestration: invokes workflow (evidence: `app/routes/agent.py`)
- Workflow orchestration → Data fetch: runs stage (evidence: `app/agents/langgraph_workflow.py`)
- Workflow orchestration → Demand forecast: runs stage (evidence: `app/agents/langgraph_workflow.py`)
- Workflow orchestration → Order optimization: runs stage (evidence: `app/agents/langgraph_workflow.py`)
- Workflow orchestration → Budget review: runs stage (evidence: `app/agents/langgraph_workflow.py`)
- Workflow orchestration → Proposal negotiation: reviews proposals
- Workflow orchestration → Purchase actions: runs stage (evidence: `app/agents/langgraph_workflow.py`)
- Workflow orchestration → Cycle state: shares state (evidence: `app/agents/langgraph_workflow.py`)
- Data fetch → Application database: reads supply data (evidence: `app/agents/nodes/fetch_data_node.py`)
- Demand forecast → LLM service: uses model service
- Demand forecast → Progress streaming: emits progress (evidence: `app/agents/nodes/forecast_node.py`)
- Proposal negotiation → Progress streaming: emits progress (evidence: `app/agents/nodes/review_node.py`)
- Purchase actions → Application database: writes orders (evidence: `app/agents/nodes/action_node.py`)
- Workflow orchestration → Persistent memory: saves run summary (evidence: `app/agents/langgraph_workflow.py`)
- Supply-chain endpoints → Application database: accesses records (evidence: `app/routes/persistence.py`)
- Memory endpoints → Application database: accesses memory (evidence: `app/routes/persistence.py`)
- Persistent memory → Application database: persists records (evidence: `app/persistence/persistent_memory.py`)
- Agent endpoints → Progress streaming: streams job updates (evidence: `app/routes/agent.py`)
