GeoSupply Copilot - System Architecture & Data Flow

Dashboard UI / HTML, CSS, JavaScript overview / operations / analytics / analyst / evaluation

Overview

Executive brief, scenario status, priority queue, geopolitical watch, and key metrics.

First scan

Operations

Order book, selected order details, alert actions, snooze notes, and change history.

Persistent

Analytics

Risk distribution, lane insights, supplier scorecards, inventory health, and demand shock views.

Decision support

Analyst Q&A

Plain-English questions answered from retrieved supply-chain evidence and fallback rules.

Grounded AI

Evaluation

Ground-truth comparison, top-risk overlap, service breach hits, and stockout hits.

Audit view

Order & Supplier Detail

Shipment context, supplier performance, recommended alternatives, and risk explanations.

Traceable

Down / User intentOpening the site, changing scenarios, editing orders, or asking a question all converge on the application layer.

Application Orchestration / Flask validate -> enrich -> summarize -> render -> export

Request Router

Entry

Serves dashboard views, scenario controls, and form submissions.
Applies CSRF protection and security headers before responses leave the app.

Scenario Assembly

Context

Loads selected scenario, scenario news, suppliers, performance, macro indicators, and ground truth.
Builds scenario snapshots and comparison deltas for side-by-side operating views.
Delivers a complete, consistent dashboard state for each view.

Operations Control

Action

Saves, deletes, and selects orders while preserving durable audit history.
Records alert actions, notes, alternate supplier choices, and snooze dates.
Explains individual order risk through traceable, structured responses.

Analyst Q&A

RAG

Builds a searchable corpus from orders, suppliers, performance, and news.
Retrieves the most relevant snippets with TF-IDF and cosine similarity.

Analytics Builder

Metrics

Generates alerts, risk distribution, lane insights, supplier scorecards, and inventory scorecards.
Computes evaluation results against scenario ground truth.

Exports

Evidence

Returns evaluation and comparison snapshots as structured downloads.
Keeps scenario evidence portable for demos, analysis, and review.

Down / Deterministic analysisThe server enriches raw orders into an operator-ready picture before model-grounded analyst synthesis.

Risk Engine / Scenario Engine / Analytics orders -> exposure -> severity -> recommended action

Severity Model

Scores geopolitical exposure, transit slippage, supplier reliability, commercial criticality, and sourcing concentration.

0-1 risk

Order Enrichment

Combines order book rows with supplier, performance, news, and inventory context.

Control tower row

Alternate Sourcing

Finds safer suppliers outside blocked countries and ranks them by resilience signals.

Mitigation path

Inventory Health

Calculates fill rate, safety stock, reorder point, EOQ, days of supply, and stockout pressure.

Service risk

Executive Brief

Synthesizes the current state into an analyst-style headline, brief, and operating focus.

Narrative layer

What-if

Demand shock scenarios estimate depletion weeks, revised safety stock, and capacity gaps.

Explainability

Order-level explanations expose the drivers behind a score instead of only showing a number.

Evaluation

Ground-truth metrics check whether the system surfaces the expected high-risk orders.

Scenario

Snapshots make current and comparison scenarios portable across dashboard and export routes.

Policy

Analyst policy inputs separate observed data from assumptions used to reason about risk.

Down / Durable recordReference data, scenario bundles, operational records, and order history form the durable operating record.

Data Foundation / SQLite + Structured Files orders / reference / scenarios / audit

Operational Orders

SQLite persists active orders, dashboard edits, and workflow state across sessions.

Order book

Reference Inputs

Suppliers, shipments, performance, demand forecast, and scenario news are organized as structured inputs.

Reference data

Audit Trail

Order create, update, delete, and alert action history provide traceability.

Evidence

Scenario Bundles

Scenario-specific orders, demand history, inventory, policy, and ground truth drive demos.

Comparisons

AI path / Grounded modelThe analyst path sends retrieved context to an OpenAI-compatible chat endpoint, then validates the response before display.

OpenAI-Compatible Endpoint / Local or Cloud swappable model endpoint

Grounding TF-IDF Retrieval Question-specific snippets are selected from orders, suppliers, performance, and news.

Context

Analyst OpenAI-Compatible LLM A local or cloud endpoint can generate concise analyst answers from retrieved evidence.

Check

Fallback Rule Engine If the model is unavailable or returns an invalid response, deterministic answers still serve the user.

Model agnostic

Any chat API with OpenAI-compatible responses can be swapped without changing the core workflow.

Citation filter

Returned citations are filtered to retrieved source IDs before they reach the UI.

No vacuum

The prompt instructs the model to answer only from provided supply-chain context.

Fallback mode

Built-in answers cover highest risk, delays, supplier alternatives, and specific order IDs.

Plain text

The analyst response is compact, action-oriented, and suitable for dashboard display.

Flow Diagrams / Left to Right dashboard / analyst / operations / export

Open Dashboard

Open control
tower

Load scenario
data

Score and
summarize

Render
insights

Ask Analyst Question

Ask plain
question

Retrieve
snippets

Generate
answer

Show answer
+ sources

Act On Alert

Select high
risk order

Choose
alternate

Add notes
or snooze

Persist audit
history

Compare & Export

Choose
scenarios

Compute
deltas

Evaluate
ground truth

Download
evidence

Primary data / process flow

AI call / fallback boundary

Durable / confirmed / trusted path

Risk / attention / intervention point

Back to the case study