# chinmayeeparida/retail-multi-agent architecture

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

- Interactive diagram: https://gitdiagram.com/chinmayeeparida/retail-multi-agent
- Repository: https://github.com/chinmayeeparida/retail-multi-agent

## Overview

This is a retail replenishment operations system: store requests are reviewed into a packing list, warehouse staff label and pack goods, a trip is approved and dispatched, stores record receipts, and a manager receives a trip report. Separate branches cover dashboard visibility, new-product approval, and distributing new-item stock. The README documents the main workflow; source-index references support several internal calls, but unsampled modules are not treated as inspected.

Main entry points: [`agent1_packing.py`](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/agent1_packing.py) (Packing Agent), [`agent3_report.py`](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/agent3_report.py) (Report Agent), [`agent2_trip.py`](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/agent2_trip.py) (Trip Agent), [`schema.sql`](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/schema.sql) (SQLite Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_store["Store Operations"]
  node_stock_request["Stock Request App"]
  node_receiving_app["Replenishment App<br/>[store_app.py]"]
  node_receiving["Store Receiving<br/>[store_receiving.py]"]
end

subgraph group_warehouse["Warehouse Logistics"]
  node_packing_app["Packaging App<br/>[packing_app.py]"]
  node_warehouse_view["Warehouse View<br/>[warehouse_view.py]"]
end

subgraph group_agents["Agents and Controls"]
  node_agent1["Packing Agent<br/>[agent1_packing.py]"]
  node_allocation["Stock Allocation<br/>[allocation.py]"]
  node_agent2["Trip Agent<br/>[agent2_trip.py]"]
  node_agent3["Report Agent<br/>[agent3_report.py]"]
  node_agent4["New Product Agent"]
  node_guardrails["Guardrails<br/>[guardrails.py]"]
  node_alerts["Warehouse Alerts<br/>[alerts.py]"]
  node_distribute["New Stock Distribution"]
  node_pipeline["Weekly Pipeline<br/>[pipeline.py]"]
end

subgraph group_data["Dashboard and Data"]
  node_dashboard["Control Room<br/>[app.py]"]
  node_screen_logic["Screen Logic<br/>[screen_logic.py]"]
  node_theme["Shared UI Theme<br/>[ui_theme.py]"]
  node_database[("SQLite Database<br/>[schema.sql]")]
end

node_store_staff(("Store Staff"))
node_warehouse_staff(("Warehouse Staff"))
node_vendor(("Vendor"))
node_operations_head(("Operations Head"))
node_mail["Email / Outbox"]
node_gemini["Gemini AI"]

node_store_staff -->|"submits requests"| node_stock_request
node_stock_request -->|"creates requests for"| node_agent1
node_agent1 -->|"allocates stock"| node_allocation
node_agent1 -->|"checks rules"| node_guardrails
node_agent1 -->|"saves packing decisions"| node_database
node_agent1 -->|"requests barcode labels"| node_warehouse_staff
node_warehouse_staff -->|"records packing"| node_packing_app
node_packing_app -->|"provides packed stock"| node_agent2
node_agent2 -->|"checks rules"| node_guardrails
node_agent2 -->|"records trip and stock"| node_database
node_agent2 -->|"dispatches deliveries to"| node_receiving_app
node_store_staff -->|"checks deliveries"| node_receiving_app
node_receiving_app -->|"records receipt"| node_receiving
node_receiving -->|"saves receipt"| node_database
node_receiving -->|"raises alerts"| node_alerts
node_receiving -->|"completes trip data for"| node_agent3
node_agent3 -->|"reads and saves report data"| node_database
node_agent3 -.->|"drafts summary with"| node_gemini
node_agent3 -->|"sends report"| node_mail
node_agent3 -->|"reports to"| node_operations_head
node_vendor -->|"supplies product details"| node_agent4
node_agent4 -->|"saves approved product"| node_database
node_agent4 -->|"enables product requests"| node_store_staff
node_distribute -->|"uses stock rules"| node_allocation
node_warehouse_staff -->|"reviews alerts and work"| node_warehouse_view
node_warehouse_view -->|"shows alerts"| node_alerts
node_dashboard -->|"uses screen logic"| node_screen_logic
node_dashboard -->|"applies shared styling"| node_theme
node_screen_logic -->|"reads operational data"| node_database
node_screen_logic -->|"invokes packing workflow"| node_agent1
node_screen_logic -->|"invokes trip workflow"| node_agent2
node_screen_logic -->|"invokes product workflow"| node_agent4
node_pipeline -->|"runs weekly step"| node_agent1
node_pipeline -->|"runs daily trips"| node_agent2
node_pipeline -->|"runs trip reports"| node_agent3
node_pipeline -->|"runs store check"| node_receiving

click node_stock_request "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/stock_request_app.py"
click node_receiving_app "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/store_app.py"
click node_receiving "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/store_receiving.py"
click node_packing_app "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/packing_app.py"
click node_warehouse_view "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/warehouse_view.py"
click node_agent1 "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/agent1_packing.py"
click node_allocation "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/allocation.py"
click node_agent2 "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/agent2_trip.py"
click node_agent3 "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/agent3_report.py"
click node_agent4 "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/agent4_new_product.py"
click node_guardrails "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/guardrails.py"
click node_alerts "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/alerts.py"
click node_distribute "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/distribute_new_stock.py"
click node_pipeline "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/pipeline.py"
click node_dashboard "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/app.py"
click node_screen_logic "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/screen_logic.py"
click node_theme "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/ui_theme.py"
click node_database "https://github.com/chinmayeeparida/retail-multi-agent/blob/main/schema.sql"

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_stock_request,node_receiving_app,node_receiving toneBlue
class node_packing_app,node_warehouse_view toneAmber
class node_agent1,node_allocation,node_agent2,node_agent3,node_agent4,node_guardrails,node_alerts,node_distribute,node_pipeline toneMint
class node_dashboard,node_screen_logic,node_theme,node_database toneRose
class node_store_staff,node_warehouse_staff,node_vendor,node_operations_head,node_mail,node_gemini toneIndigo
```

## Components

### Store Operations

- [Stock Request App](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/stock_request_app.py): `stock_request_app.py`
- [Replenishment App](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/store_app.py): `store_app.py`
- [Store Receiving](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/store_receiving.py): `store_receiving.py`

### Warehouse Logistics

- [Packaging App](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/packing_app.py): `packing_app.py`
- [Warehouse View](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/warehouse_view.py): `warehouse_view.py`

### Agents and Controls

- [Packing Agent](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/agent1_packing.py): `agent1_packing.py`
- [Stock Allocation](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/allocation.py): `allocation.py`
- [Trip Agent](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/agent2_trip.py): `agent2_trip.py`
- [Report Agent](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/agent3_report.py): `agent3_report.py`
- [New Product Agent](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/agent4_new_product.py): `agent4_new_product.py`
- [Guardrails](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/guardrails.py): `guardrails.py`
- [Warehouse Alerts](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/alerts.py): `alerts.py`
- [New Stock Distribution](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/distribute_new_stock.py): `distribute_new_stock.py`
- [Weekly Pipeline](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/pipeline.py): `pipeline.py`

### Dashboard and Data

- [Control Room](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/app.py): `app.py`
- [Screen Logic](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/screen_logic.py): `screen_logic.py`
- [Shared UI Theme](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/ui_theme.py): `ui_theme.py`
- [SQLite Database](https://github.com/chinmayeeparida/retail-multi-agent/blob/main/schema.sql): `schema.sql`

### Other components

- **Store Staff**
- **Warehouse Staff**
- **Vendor**
- **Operations Head**
- **Email / Outbox**
- **Gemini AI**

## Connections

- Store Staff → Stock Request App: submits requests (evidence: `README.md`)
- Stock Request App → Packing Agent: creates requests for (evidence: `README.md`)
- Packing Agent → Stock Allocation: allocates stock (evidence: `agent1_packing.py`)
- Packing Agent → Guardrails: checks rules (evidence: `agent1_packing.py`)
- Packing Agent → SQLite Database: saves packing decisions (evidence: `README.md`)
- Packing Agent → Warehouse Staff: requests barcode labels (evidence: `README.md`)
- Warehouse Staff → Packaging App: records packing (evidence: `README.md`)
- Packaging App → Trip Agent: provides packed stock (evidence: `README.md`)
- Trip Agent → Guardrails: checks rules (evidence: `agent2_trip.py`)
- Trip Agent → SQLite Database: records trip and stock (evidence: `README.md`)
- Trip Agent → Replenishment App: dispatches deliveries to (evidence: `README.md`)
- Store Staff → Replenishment App: checks deliveries (evidence: `README.md`)
- Replenishment App → Store Receiving: records receipt (evidence: `README.md`)
- Store Receiving → SQLite Database: saves receipt (evidence: `store_receiving.py`)
- Store Receiving → Warehouse Alerts: raises alerts (evidence: `store_receiving.py`)
- Store Receiving → Report Agent: completes trip data for (evidence: `README.md`)
- Report Agent → SQLite Database: reads and saves report data (evidence: `README.md`)
- Report Agent → Gemini AI: drafts summary with (evidence: `README.md`)
- Report Agent → Email / Outbox: sends report (evidence: `agent3_report.py`)
- Report Agent → Operations Head: reports to (evidence: `README.md`)
- Vendor → New Product Agent: supplies product details (evidence: `README.md`)
- New Product Agent → SQLite Database: saves approved product (evidence: `README.md`)
- New Product Agent → Store Staff: enables product requests (evidence: `README.md`)
- New Stock Distribution → Stock Allocation: uses stock rules (evidence: `distribute_new_stock.py`)
- Warehouse Staff → Warehouse View: reviews alerts and work (evidence: `README.md`)
- Warehouse View → Warehouse Alerts: shows alerts (evidence: `warehouse_view.py`)
- Control Room → Screen Logic: uses screen logic (evidence: `app.py`)
- Control Room → Shared UI Theme: applies shared styling (evidence: `app.py`)
- Screen Logic → SQLite Database: reads operational data (evidence: `screen_logic.py`)
- Screen Logic → Packing Agent: invokes packing workflow (evidence: `screen_logic.py`)
- Screen Logic → Trip Agent: invokes trip workflow (evidence: `screen_logic.py`)
- Screen Logic → New Product Agent: invokes product workflow (evidence: `screen_logic.py`)
- Weekly Pipeline → Packing Agent: runs weekly step (evidence: `pipeline.py`)
- Weekly Pipeline → Trip Agent: runs daily trips (evidence: `pipeline.py`)
- Weekly Pipeline → Report Agent: runs trip reports (evidence: `pipeline.py`)
- Weekly Pipeline → Store Receiving: runs store check (evidence: `pipeline.py`)