# surendraraju09/sentinel-sc architecture

> Architecture diagram of the GitHub repository surendraraju09/sentinel-sc, 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/surendraraju09/sentinel-sc
- Repository: https://github.com/surendraraju09/sentinel-sc

## Overview

Sentinel-SC is a supply-chain disruption control tower. Users submit a news signal or fixture through the dashboard or API; the workflow extracts and correlates it with shipment records, assesses material shortage and order exposure, and—when recovery is needed—evaluates options before a human approval decision. The deterministic impact and recovery engines form the main internal decision layer, backed by mock ERP data and typed event, impact, and recovery contracts. Evidence is limited to the supplied excerpts and SOURCE INDEX; unsampled API and workflow details are not expanded beyond supported links.

Main entry points: [`graph.py`](https://github.com/surendraraju09/sentinel-sc/blob/master/graph.py) (Workflow orchestrator), [`agents/recovery_agent.py`](https://github.com/surendraraju09/sentinel-sc/blob/master/agents/recovery_agent.py) (Recovery agent), [`agents/signal_agent.py`](https://github.com/surendraraju09/sentinel-sc/blob/master/agents/signal_agent.py) (Signal agent), [`engine/impact_math.py`](https://github.com/surendraraju09/sentinel-sc/blob/master/engine/impact_math.py) (Impact assessment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Product entry points"]
  node_dashboard["Control tower UI<br/>[app.py]"]
  node_api["HTTP API<br/>[api.py]"]
  node_workflow["Workflow orchestrator<br/>[graph.py]"]
end

subgraph group_signal["Signal intelligence"]
  node_signal_agent["Signal agent<br/>[signal_agent.py]"]
  node_serp_client["News fallback client<br/>[serp_client.py]"]
end

subgraph group_decision["Impact and recovery"]
  node_impact["Impact assessment<br/>[impact_math.py]"]
  node_bom["BOM traversal<br/>[bom_traversal.py]"]
  node_recovery_agent["Recovery agent<br/>[recovery_agent.py]"]
  node_recovery_calc["Option calculator"]
  node_constraints["Constraint evaluator"]
end

subgraph group_data["ERP and contracts"]
  node_erp[("Mock ERP database<br/>[mock_erp.db]")]
  node_event_schema["Event contract<br/>[events.py]"]
  node_impact_schema["Impact contract<br/>[impact.py]"]
  node_recovery_schema["Recovery contract<br/>[recovery.py]"]
end

node_user(("Operations user"))
node_api_client(("API client"))
node_serp_api["SerpAPI"]
node_human(("Approver"))
node_llm["OpenAI service"]

node_user -->|"submits scenario"| node_dashboard
node_api_client -->|"sends request"| node_api
node_dashboard -->|"invokes workflow"| node_workflow
node_api -->|"uses workflow"| node_workflow
node_workflow -->|"ingests signal"| node_signal_agent
node_signal_agent -->|"fetches news"| node_serp_client
node_serp_client -->|"queries"| node_serp_api
node_signal_agent -->|"correlates shipment"| node_erp
node_signal_agent -->|"creates event"| node_event_schema
node_workflow -->|"computes impact"| node_impact
node_impact -->|"reads records"| node_erp
node_impact -->|"finds affected work"| node_bom
node_impact -->|"returns assessment"| node_impact_schema
node_workflow -->|"proposes recovery"| node_recovery_agent
node_recovery_agent -->|"evaluates options"| node_recovery_calc
node_recovery_agent -->|"reads templates"| node_erp
node_recovery_agent -.->|"summarizes plan"| node_llm
node_recovery_calc -->|"evaluates rules"| node_constraints
node_constraints -->|"reads rulebook"| node_erp
node_recovery_agent -->|"returns plan"| node_recovery_schema
node_workflow -->|"requests decision"| node_human

click node_dashboard "https://github.com/surendraraju09/sentinel-sc/blob/master/app.py"
click node_api "https://github.com/surendraraju09/sentinel-sc/blob/master/api.py"
click node_workflow "https://github.com/surendraraju09/sentinel-sc/blob/master/graph.py"
click node_signal_agent "https://github.com/surendraraju09/sentinel-sc/blob/master/agents/signal_agent.py"
click node_serp_client "https://github.com/surendraraju09/sentinel-sc/blob/master/integrations/serp_client.py"
click node_impact "https://github.com/surendraraju09/sentinel-sc/blob/master/engine/impact_math.py"
click node_bom "https://github.com/surendraraju09/sentinel-sc/blob/master/engine/bom_traversal.py"
click node_recovery_agent "https://github.com/surendraraju09/sentinel-sc/blob/master/agents/recovery_agent.py"
click node_recovery_calc "https://github.com/surendraraju09/sentinel-sc/blob/master/engine/recovery_calculator.py"
click node_constraints "https://github.com/surendraraju09/sentinel-sc/blob/master/engine/constraint_engine.py"
click node_erp "https://github.com/surendraraju09/sentinel-sc/blob/master/erp/mock_erp.db"
click node_event_schema "https://github.com/surendraraju09/sentinel-sc/blob/master/schemas/events.py"
click node_impact_schema "https://github.com/surendraraju09/sentinel-sc/blob/master/schemas/impact.py"
click node_recovery_schema "https://github.com/surendraraju09/sentinel-sc/blob/master/schemas/recovery.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_dashboard,node_api,node_workflow,node_user,node_api_client toneBlue
class node_signal_agent,node_serp_client toneAmber
class node_impact,node_bom,node_recovery_agent,node_recovery_calc,node_constraints,node_serp_api toneMint
class node_erp,node_event_schema,node_impact_schema,node_recovery_schema toneRose
class node_human,node_llm toneIndigo
```

## Components

### Product entry points

- [Control tower UI](https://github.com/surendraraju09/sentinel-sc/blob/master/app.py): `app.py`
- [HTTP API](https://github.com/surendraraju09/sentinel-sc/blob/master/api.py): `api.py`
- [Workflow orchestrator](https://github.com/surendraraju09/sentinel-sc/blob/master/graph.py): `graph.py`

### Signal intelligence

- [Signal agent](https://github.com/surendraraju09/sentinel-sc/blob/master/agents/signal_agent.py): `agents/signal_agent.py`
- [News fallback client](https://github.com/surendraraju09/sentinel-sc/blob/master/integrations/serp_client.py): `integrations/serp_client.py`

### Impact and recovery

- [Impact assessment](https://github.com/surendraraju09/sentinel-sc/blob/master/engine/impact_math.py): `engine/impact_math.py`
- [BOM traversal](https://github.com/surendraraju09/sentinel-sc/blob/master/engine/bom_traversal.py): `engine/bom_traversal.py`
- [Recovery agent](https://github.com/surendraraju09/sentinel-sc/blob/master/agents/recovery_agent.py): `agents/recovery_agent.py`
- [Option calculator](https://github.com/surendraraju09/sentinel-sc/blob/master/engine/recovery_calculator.py): `engine/recovery_calculator.py`
- [Constraint evaluator](https://github.com/surendraraju09/sentinel-sc/blob/master/engine/constraint_engine.py): `engine/constraint_engine.py`

### ERP and contracts

- [Mock ERP database](https://github.com/surendraraju09/sentinel-sc/blob/master/erp/mock_erp.db): `erp/mock_erp.db`
- [Event contract](https://github.com/surendraraju09/sentinel-sc/blob/master/schemas/events.py): `schemas/events.py`
- [Impact contract](https://github.com/surendraraju09/sentinel-sc/blob/master/schemas/impact.py): `schemas/impact.py`
- [Recovery contract](https://github.com/surendraraju09/sentinel-sc/blob/master/schemas/recovery.py): `schemas/recovery.py`

### Other components

- **Operations user**
- **API client**
- **SerpAPI**
- **Approver**
- **OpenAI service**

## Connections

- Operations user → Control tower UI: submits scenario (evidence: `app.py`)
- API client → HTTP API: sends request (evidence: `api.py`)
- Control tower UI → Workflow orchestrator: invokes workflow (evidence: `app.py`)
- HTTP API → Workflow orchestrator: uses workflow (evidence: `api.py`)
- Workflow orchestrator → Signal agent: ingests signal (evidence: `graph.py`)
- Signal agent → News fallback client: fetches news (evidence: `agents/signal_agent.py`)
- News fallback client → SerpAPI: queries (evidence: `integrations/serp_client.py`)
- Signal agent → Mock ERP database: correlates shipment (evidence: `agents/signal_agent.py`)
- Signal agent → Event contract: creates event (evidence: `schemas/events.py`)
- Workflow orchestrator → Impact assessment: computes impact (evidence: `graph.py`)
- Impact assessment → Mock ERP database: reads records (evidence: `engine/impact_math.py`)
- Impact assessment → BOM traversal: finds affected work (evidence: `engine/impact_math.py`)
- Impact assessment → Impact contract: returns assessment (evidence: `schemas/impact.py`)
- Workflow orchestrator → Recovery agent: proposes recovery (evidence: `graph.py`)
- Recovery agent → Option calculator: evaluates options (evidence: `agents/recovery_agent.py`)
- Recovery agent → Mock ERP database: reads templates (evidence: `agents/recovery_agent.py`)
- Recovery agent → OpenAI service: summarizes plan (evidence: `agents/recovery_agent.py`)
- Option calculator → Constraint evaluator: evaluates rules (evidence: `engine/recovery_calculator.py`)
- Constraint evaluator → Mock ERP database: reads rulebook (evidence: `engine/constraint_engine.py`)
- Recovery agent → Recovery contract: returns plan (evidence: `agents/recovery_agent.py`)
- Workflow orchestrator → Approver: requests decision (evidence: `graph.py`)
