# sohana881/supplyshield architecture

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

- Interactive diagram: https://gitdiagram.com/sohana881/supplyshield
- Repository: https://github.com/sohana881/supplyshield

## Overview

SupplyShield is a supply-chain disruption recovery platform. Operators use the control-room UI to inspect incident and operational data, request recovery analysis, and review a policy-governed recovery result. The recovery service combines deterministic supply, shipment, route, supplier, and finance facts with specialist-agent analysis; security controls constrain sensitive actions and record audit events. The README describes these product capabilities, while several internal relationships are supported only by the source index, so unsampled implementation details are not expanded.

Main entry points: [`services/recovery_service.py`](https://github.com/sohana881/supplyshield/blob/main/services/recovery_service.py) (Recovery Service), [`agents/command_agent/agent.py`](https://github.com/sohana881/supplyshield/blob/main/agents/command_agent/agent.py) (Command Agent), [`security/engine.py`](https://github.com/sohana881/supplyshield/blob/main/security/engine.py) (Policy Engine), [`backend/main.py`](https://github.com/sohana881/supplyshield/blob/main/backend/main.py) (SupplyShield API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Control Room"]
  node_ui["Control Room UI<br/>[App.jsx]"]
  node_api["SupplyShield API<br/>[main.py]"]
end

subgraph group_recovery["Recovery Orchestration"]
  node_recovery_service["Recovery Service"]
  node_simulation["Disruption Scenarios<br/>[scenarios.py]"]
end

subgraph group_agents["Specialist Agents"]
  node_command["Command Agent<br/>[agent.py]"]
  node_inventory_agent["Inventory Agent<br/>[agent.py]"]
  node_shipment_agent["Shipment Agent<br/>[agent.py]"]
  node_supplier_agent["Supplier Agent<br/>[agent.py]"]
  node_logistics_agent["Logistics Agent<br/>[agent.py]"]
  node_finance_agent["Finance Agent<br/>[agent.py]"]
  node_risk_agent["Risk Agent<br/>[agent.py]"]
  node_procurement_agent["Procurement Agent<br/>[agent.py]"]
end

subgraph group_facts["Operational Facts"]
  node_inventory_tools["Inventory Analysis<br/>[inventory_tools.py]"]
  node_shipment_tools["Shipment Analysis<br/>[shipment_tools.py]"]
  node_supplier_tools["Supplier Options<br/>[supplier_tools.py]"]
  node_logistics_tools["Route Analysis<br/>[logistics_tools.py]"]
  node_finance_tools["Finance Checks<br/>[finance_tools.py]"]
  node_procurement_tools["Procurement Proposals"]
end

subgraph group_governance["Security &amp; Audit"]
  node_security_engine["Policy Engine<br/>[engine.py]"]
  node_guardrails["Security Guardrails<br/>[guardrails.py]"]
  node_permissions["Agent Permissions<br/>[permissions.py]"]
  node_policies["Policy Configuration<br/>[policies.py]"]
  node_audit["Audit Events<br/>[audit.py]"]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_ui
node_ui -->|"requests recovery"| node_api
node_api -->|"invokes"| node_recovery_service
node_recovery_service -->|"runs analysis"| node_command
node_command -->|"delegates to"| node_inventory_agent
node_command -->|"delegates to"| node_shipment_agent
node_command -->|"delegates to"| node_supplier_agent
node_command -->|"delegates to"| node_logistics_agent
node_command -->|"delegates to"| node_finance_agent
node_command -->|"delegates to"| node_risk_agent
node_command -->|"delegates to"| node_procurement_agent
node_inventory_agent -->|"uses tools"| node_inventory_tools
node_shipment_agent -->|"uses tools"| node_shipment_tools
node_supplier_agent -->|"uses tools"| node_supplier_tools
node_logistics_agent -->|"uses tools"| node_logistics_tools
node_finance_agent -->|"uses tools"| node_finance_tools
node_procurement_agent -->|"uses tools"| node_procurement_tools
node_recovery_service -->|"verifies facts"| node_inventory_tools
node_recovery_service -->|"verifies facts"| node_shipment_tools
node_recovery_service -->|"finds options"| node_supplier_tools
node_recovery_service -->|"finds routes"| node_logistics_tools
node_recovery_service -->|"checks budget"| node_finance_tools
node_recovery_service -->|"checks controls"| node_guardrails
node_guardrails -->|"routes checks"| node_security_engine
node_security_engine -->|"checks access"| node_permissions
node_security_engine -->|"loads policy"| node_policies
node_security_engine -->|"writes events"| node_audit
node_api -->|"secures requests"| node_security_engine
node_simulation -.->|"provides scenarios"| node_operator

click node_ui "https://github.com/sohana881/supplyshield/blob/main/frontend/src/App.jsx"
click node_api "https://github.com/sohana881/supplyshield/blob/main/backend/main.py"
click node_recovery_service "https://github.com/sohana881/supplyshield/blob/main/services/recovery_service.py"
click node_command "https://github.com/sohana881/supplyshield/blob/main/agents/command_agent/agent.py"
click node_inventory_agent "https://github.com/sohana881/supplyshield/blob/main/agents/inventory_agent/agent.py"
click node_shipment_agent "https://github.com/sohana881/supplyshield/blob/main/agents/shipment_agent/agent.py"
click node_supplier_agent "https://github.com/sohana881/supplyshield/blob/main/agents/supplier_agent/agent.py"
click node_logistics_agent "https://github.com/sohana881/supplyshield/blob/main/agents/logistics_agent/agent.py"
click node_finance_agent "https://github.com/sohana881/supplyshield/blob/main/agents/finance_agent/agent.py"
click node_risk_agent "https://github.com/sohana881/supplyshield/blob/main/agents/risk_agent/agent.py"
click node_procurement_agent "https://github.com/sohana881/supplyshield/blob/main/agents/procurement_agent/agent.py"
click node_inventory_tools "https://github.com/sohana881/supplyshield/blob/main/tools/inventory_tools.py"
click node_shipment_tools "https://github.com/sohana881/supplyshield/blob/main/tools/shipment_tools.py"
click node_supplier_tools "https://github.com/sohana881/supplyshield/blob/main/tools/supplier_tools.py"
click node_logistics_tools "https://github.com/sohana881/supplyshield/blob/main/tools/logistics_tools.py"
click node_finance_tools "https://github.com/sohana881/supplyshield/blob/main/tools/finance_tools.py"
click node_procurement_tools "https://github.com/sohana881/supplyshield/blob/main/tools/procurement_tools.py"
click node_security_engine "https://github.com/sohana881/supplyshield/blob/main/security/engine.py"
click node_guardrails "https://github.com/sohana881/supplyshield/blob/main/security/guardrails.py"
click node_permissions "https://github.com/sohana881/supplyshield/blob/main/security/permissions.py"
click node_policies "https://github.com/sohana881/supplyshield/blob/main/security/policies.py"
click node_audit "https://github.com/sohana881/supplyshield/blob/main/security/audit.py"
click node_simulation "https://github.com/sohana881/supplyshield/blob/main/simulation/scenarios.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_ui,node_api toneBlue
class node_recovery_service,node_simulation toneAmber
class node_command,node_inventory_agent,node_shipment_agent,node_supplier_agent,node_logistics_agent,node_finance_agent,node_risk_agent,node_procurement_agent toneMint
class node_inventory_tools,node_shipment_tools,node_supplier_tools,node_logistics_tools,node_finance_tools,node_procurement_tools toneRose
class node_security_engine,node_guardrails,node_permissions,node_policies,node_audit,node_operator toneIndigo
```

## Components

### Control Room

- [Control Room UI](https://github.com/sohana881/supplyshield/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [SupplyShield API](https://github.com/sohana881/supplyshield/blob/main/backend/main.py): `backend/main.py`

### Recovery Orchestration

- [Recovery Service](https://github.com/sohana881/supplyshield/blob/main/services/recovery_service.py): `services/recovery_service.py`
- [Disruption Scenarios](https://github.com/sohana881/supplyshield/blob/main/simulation/scenarios.py): `simulation/scenarios.py`

### Specialist Agents

- [Command Agent](https://github.com/sohana881/supplyshield/blob/main/agents/command_agent/agent.py): `agents/command_agent/agent.py`
- [Inventory Agent](https://github.com/sohana881/supplyshield/blob/main/agents/inventory_agent/agent.py): `agents/inventory_agent/agent.py`
- [Shipment Agent](https://github.com/sohana881/supplyshield/blob/main/agents/shipment_agent/agent.py): `agents/shipment_agent/agent.py`
- [Supplier Agent](https://github.com/sohana881/supplyshield/blob/main/agents/supplier_agent/agent.py): `agents/supplier_agent/agent.py`
- [Logistics Agent](https://github.com/sohana881/supplyshield/blob/main/agents/logistics_agent/agent.py): `agents/logistics_agent/agent.py`
- [Finance Agent](https://github.com/sohana881/supplyshield/blob/main/agents/finance_agent/agent.py): `agents/finance_agent/agent.py`
- [Risk Agent](https://github.com/sohana881/supplyshield/blob/main/agents/risk_agent/agent.py): `agents/risk_agent/agent.py`
- [Procurement Agent](https://github.com/sohana881/supplyshield/blob/main/agents/procurement_agent/agent.py): `agents/procurement_agent/agent.py`

### Operational Facts

- [Inventory Analysis](https://github.com/sohana881/supplyshield/blob/main/tools/inventory_tools.py): `tools/inventory_tools.py`
- [Shipment Analysis](https://github.com/sohana881/supplyshield/blob/main/tools/shipment_tools.py): `tools/shipment_tools.py`
- [Supplier Options](https://github.com/sohana881/supplyshield/blob/main/tools/supplier_tools.py): `tools/supplier_tools.py`
- [Route Analysis](https://github.com/sohana881/supplyshield/blob/main/tools/logistics_tools.py): `tools/logistics_tools.py`
- [Finance Checks](https://github.com/sohana881/supplyshield/blob/main/tools/finance_tools.py): `tools/finance_tools.py`
- [Procurement Proposals](https://github.com/sohana881/supplyshield/blob/main/tools/procurement_tools.py): `tools/procurement_tools.py`

### Security & Audit

- [Policy Engine](https://github.com/sohana881/supplyshield/blob/main/security/engine.py): `security/engine.py`
- [Security Guardrails](https://github.com/sohana881/supplyshield/blob/main/security/guardrails.py): `security/guardrails.py`
- [Agent Permissions](https://github.com/sohana881/supplyshield/blob/main/security/permissions.py): `security/permissions.py`
- [Policy Configuration](https://github.com/sohana881/supplyshield/blob/main/security/policies.py): `security/policies.py`
- [Audit Events](https://github.com/sohana881/supplyshield/blob/main/security/audit.py): `security/audit.py`

### Other components

- **Operator**

## Connections

- Operator → Control Room UI: uses
- Control Room UI → SupplyShield API: requests recovery (evidence: `frontend/src/App.jsx`)
- SupplyShield API → Recovery Service: invokes (evidence: `backend/main.py`)
- Recovery Service → Command Agent: runs analysis
- Command Agent → Inventory Agent: delegates to (evidence: `agents/command_agent/agent.py`)
- Command Agent → Shipment Agent: delegates to (evidence: `agents/command_agent/agent.py`)
- Command Agent → Supplier Agent: delegates to (evidence: `agents/command_agent/agent.py`)
- Command Agent → Logistics Agent: delegates to (evidence: `agents/command_agent/agent.py`)
- Command Agent → Finance Agent: delegates to (evidence: `agents/command_agent/agent.py`)
- Command Agent → Risk Agent: delegates to (evidence: `agents/command_agent/agent.py`)
- Command Agent → Procurement Agent: delegates to (evidence: `agents/command_agent/agent.py`)
- Inventory Agent → Inventory Analysis: uses tools (evidence: `agents/inventory_agent/agent.py`)
- Shipment Agent → Shipment Analysis: uses tools (evidence: `agents/shipment_agent/agent.py`)
- Supplier Agent → Supplier Options: uses tools (evidence: `agents/supplier_agent/agent.py`)
- Logistics Agent → Route Analysis: uses tools (evidence: `agents/logistics_agent/agent.py`)
- Finance Agent → Finance Checks: uses tools (evidence: `agents/finance_agent/agent.py`)
- Procurement Agent → Procurement Proposals: uses tools (evidence: `agents/procurement_agent/agent.py`)
- Recovery Service → Inventory Analysis: verifies facts (evidence: `services/recovery_service.py`)
- Recovery Service → Shipment Analysis: verifies facts (evidence: `services/recovery_service.py`)
- Recovery Service → Supplier Options: finds options (evidence: `services/recovery_service.py`)
- Recovery Service → Route Analysis: finds routes (evidence: `services/recovery_service.py`)
- Recovery Service → Finance Checks: checks budget (evidence: `services/recovery_service.py`)
- Recovery Service → Security Guardrails: checks controls (evidence: `services/recovery_service.py`)
- Security Guardrails → Policy Engine: routes checks (evidence: `security/guardrails.py`)
- Policy Engine → Agent Permissions: checks access (evidence: `security/engine.py`)
- Policy Engine → Policy Configuration: loads policy (evidence: `security/engine.py`)
- Policy Engine → Audit Events: writes events (evidence: `security/engine.py`)
- SupplyShield API → Policy Engine: secures requests (evidence: `backend/main.py`)
- Disruption Scenarios → Operator: provides scenarios (evidence: `simulation/scenarios.py`)
