# ahamed-safnas/cold-chain-logistics-ai-assistant architecture

> Architecture diagram of the GitHub repository ahamed-safnas/cold-chain-logistics-ai-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahamed-safnas/cold-chain-logistics-ai-assistant
- Repository: https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant

## Overview

This repository implements a cold-chain logistics incident assistant: dispatchers ask operational questions, an agent can retrieve fleet telemetry, live corridor conditions, and compliance guidance, then presents a response and records execution traces. Separate ingestion scripts load legacy fleet data into SQL and index policy documents in Pinecone. The excerpts show the principal tool and ingestion paths; UI audit logging is only partially excerpted, and several documented product claims cannot be verified from the available source.

Main entry points: [`src/agent_tools.py`](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/agent_tools.py) (Operational tools), [`src/orchestrator.py`](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/orchestrator.py) (LLM reasoner), [`src/ui.py`](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/ui.py) (Command center), [`scripts/ingest_sop_pinecone.py`](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/scripts/ingest_sop_pinecone.py) (Policy ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Dispatcher experience"]
  node_command_center["Command center<br/>[ui.py]"]
  node_audit_log[("SQL audit log")]
  node_admin_view["Audit log viewer<br/>[ui.py]"]
end

subgraph group_agent["Incident reasoning"]
  node_agent_graph["Agent graph<br/>[orchestrator.py]"]
  node_reasoner["LLM reasoner<br/>[orchestrator.py]"]
  node_tool_dispatch["Tool dispatch<br/>[orchestrator.py]"]
  node_agent_tools["Operational tools<br/>[agent_tools.py]"]
  node_fleet_sql[("Fleet SQL view")]
  node_corridor_api["Weather API"]
  node_sop_search["SOP retrieval<br/>[agent_tools.py]"]
  node_pinecone[("Pinecone index")]
  node_llm_service["Configured LLM"]
end

subgraph group_ingestion["Data preparation"]
  node_policy_files["Policy documents"]
  node_sop_ingestion["Policy ingestion"]
  node_hash_cache[("Ingestion hash cache")]
  node_legacy_csv["Fleet dataset"]
  node_legacy_ingestion["Legacy fleet loader"]
  node_legacy_sql[("Legacy SQL table")]
end

node_dispatcher(("Dispatcher"))

node_dispatcher -->|"submits queries"| node_command_center
node_command_center -->|"streams agent updates"| node_agent_graph
node_agent_graph -->|"starts reasoning"| node_reasoner
node_reasoner -->|"invokes model"| node_llm_service
node_reasoner -->|"routes tool calls"| node_tool_dispatch
node_tool_dispatch -->|"executes registered tools"| node_agent_tools
node_tool_dispatch -->|"returns tool results"| node_reasoner
node_agent_tools -->|"queries fleet view"| node_fleet_sql
node_agent_tools -->|"fetches conditions"| node_corridor_api
node_agent_tools -->|"invokes retrieval"| node_sop_search
node_sop_search -->|"searches index"| node_pinecone
node_policy_files -->|"supplies source files"| node_sop_ingestion
node_sop_ingestion -->|"upserts chunks"| node_pinecone
node_sop_ingestion -->|"reads and updates hashes"| node_hash_cache
node_legacy_csv -->|"provides fleet rows"| node_legacy_ingestion
node_legacy_ingestion -->|"writes legacy table"| node_legacy_sql
node_command_center -->|"writes execution traces"| node_audit_log
node_admin_view -->|"queries audit records"| node_audit_log

click node_command_center "https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/ui.py"
click node_agent_graph "https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/orchestrator.py"
click node_reasoner "https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/orchestrator.py"
click node_tool_dispatch "https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/orchestrator.py"
click node_agent_tools "https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/agent_tools.py"
click node_sop_search "https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/agent_tools.py"
click node_policy_files "https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/tree/main/data/policy"
click node_sop_ingestion "https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/scripts/ingest_sop_pinecone.py"
click node_hash_cache "https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/data/cache/ingestion_hash_cache.json"
click node_legacy_csv "https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/data/raw/dynamic_supply_chain_logistics_dataset.csv"
click node_legacy_ingestion "https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/scripts/ingest_legacy_data.py"
click node_admin_view "https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/ui.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_command_center,node_audit_log,node_admin_view toneBlue
class node_agent_graph,node_reasoner,node_tool_dispatch,node_agent_tools,node_fleet_sql,node_corridor_api,node_sop_search,node_pinecone,node_llm_service toneAmber
class node_policy_files,node_sop_ingestion,node_hash_cache,node_legacy_csv,node_legacy_ingestion,node_legacy_sql toneMint
class node_dispatcher toneIndigo
```

## Components

### Dispatcher experience

- [Command center](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/ui.py): `src/ui.py`
- **SQL audit log**
- [Audit log viewer](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/ui.py): `src/ui.py`

### Incident reasoning

- [Agent graph](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/orchestrator.py): `src/orchestrator.py`
- [LLM reasoner](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/orchestrator.py): `src/orchestrator.py`
- [Tool dispatch](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/orchestrator.py): `src/orchestrator.py`
- [Operational tools](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/agent_tools.py): `src/agent_tools.py`
- **Fleet SQL view**
- **Weather API**
- [SOP retrieval](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/src/agent_tools.py): `src/agent_tools.py`
- **Pinecone index**
- **Configured LLM**

### Data preparation

- [Policy documents](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/tree/main/data/policy): `data/policy`
- [Policy ingestion](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/scripts/ingest_sop_pinecone.py): `scripts/ingest_sop_pinecone.py`
- [Ingestion hash cache](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/data/cache/ingestion_hash_cache.json): `data/cache/ingestion_hash_cache.json`
- [Fleet dataset](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/data/raw/dynamic_supply_chain_logistics_dataset.csv): `data/raw/dynamic_supply_chain_logistics_dataset.csv`
- [Legacy fleet loader](https://github.com/ahamed-safnas/cold-chain-logistics-ai-assistant/blob/main/scripts/ingest_legacy_data.py): `scripts/ingest_legacy_data.py`
- **Legacy SQL table**

### Other components

- **Dispatcher**

## Connections

- Dispatcher → Command center: submits queries (evidence: `src/ui.py`)
- Command center → Agent graph: streams agent updates (evidence: `src/ui.py`)
- Agent graph → LLM reasoner: starts reasoning (evidence: `src/orchestrator.py`)
- LLM reasoner → Configured LLM: invokes model (evidence: `src/orchestrator.py`)
- LLM reasoner → Tool dispatch: routes tool calls (evidence: `src/orchestrator.py`)
- Tool dispatch → Operational tools: executes registered tools (evidence: `src/orchestrator.py`)
- Tool dispatch → LLM reasoner: returns tool results (evidence: `src/orchestrator.py`)
- Operational tools → Fleet SQL view: queries fleet view (evidence: `src/agent_tools.py`)
- Operational tools → Weather API: fetches conditions (evidence: `src/agent_tools.py`)
- Operational tools → SOP retrieval: invokes retrieval (evidence: `src/agent_tools.py`)
- SOP retrieval → Pinecone index: searches index (evidence: `src/agent_tools.py`)
- Policy documents → Policy ingestion: supplies source files (evidence: `scripts/ingest_sop_pinecone.py`)
- Policy ingestion → Pinecone index: upserts chunks (evidence: `scripts/ingest_sop_pinecone.py`)
- Policy ingestion → Ingestion hash cache: reads and updates hashes (evidence: `scripts/ingest_sop_pinecone.py`)
- Fleet dataset → Legacy fleet loader: provides fleet rows (evidence: `scripts/ingest_legacy_data.py`)
- Legacy fleet loader → Legacy SQL table: writes legacy table (evidence: `scripts/ingest_legacy_data.py`)
- Command center → SQL audit log: writes execution traces (evidence: `src/ui.py`)
- Audit log viewer → SQL audit log: queries audit records (evidence: `src/ui.py`)
