# scarwizz/moic_inventory_management architecture

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

- Interactive diagram: https://gitdiagram.com/scarwizz/moic_inventory_management
- Repository: https://github.com/scarwizz/moic_inventory_management

## Overview

MOIC is a supply-chain decision system with an offline data-to-surrogate pipeline and an online natural-language inventory-analysis workflow. A manager submits a query through Streamlit; the LangGraph agent can retrieve a SKU demand profile, estimate policy outcomes, calculate financial impact, and return a grounded response with an execution trace. The graph also preserves the documented aggregation, feature-engineering, simulation, and model-training stages. Some pipeline handoffs are documented in code, while CatBoost and the Groq model are described only in the README; those links are cited there.

Main entry points: [`agent_core.py`](https://github.com/scarwizz/moic_inventory_management/blob/main/agent_core.py) (LangGraph agent), [`data_aggregation.py`](https://github.com/scarwizz/moic_inventory_management/blob/main/data_aggregation.py) (Sales aggregation), [`feature_engineering.py`](https://github.com/scarwizz/moic_inventory_management/blob/main/feature_engineering.py) (Demand features), [`simulation.py`](https://github.com/scarwizz/moic_inventory_management/blob/main/simulation.py) (Policy simulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Offline data pipeline"]
  node_prep["Sales preparation<br/>[dataprep.py]"]
  node_aggregation["Sales aggregation"]
  node_features["Demand features"]
  node_simulation["Policy simulation<br/>[simulation.py]"]
  node_catalogue[("Demand feature CSV")]
  node_trainingdata[("Simulation training data")]
end

subgraph group_models["Surrogate models"]
  node_training["Surrogate training"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["LangGraph agent<br/>[agent_core.py]"]
  node_sku[("SKU profile lookup<br/>[sku_store.py]")]
  node_tools["Policy and cost tools<br/>[inventory_tools.py]"]
end

subgraph group_interface["User interface"]
  node_streamlit["Streamlit dashboard<br/>[app.py]"]
end

node_manager(("Supply manager"))
node_groq["Groq Llama model"]
node_rawdata[("M5 sales data")]

node_manager -->|"submits query"| node_streamlit
node_streamlit -->|"invokes agent"| node_agent
node_agent -->|"reasons with"| node_groq
node_agent -->|"dispatches lookup"| node_sku
node_agent -->|"dispatches tools"| node_tools
node_rawdata -->|"reads sales"| node_prep
node_rawdata -->|"reads sales"| node_aggregation
node_aggregation -->|"provides series"| node_features
node_features -->|"writes profiles"| node_catalogue
node_catalogue -->|"loads profiles"| node_sku
node_features -->|"supplies features"| node_simulation
node_aggregation -->|"supplies sales"| node_simulation
node_simulation -->|"writes targets"| node_trainingdata
node_trainingdata -->|"loads observations"| node_training
node_training -.->|"exports predictors"| node_tools
node_tools -.->|"uses demand profile"| node_catalogue

click node_streamlit "https://github.com/scarwizz/moic_inventory_management/blob/main/app.py"
click node_agent "https://github.com/scarwizz/moic_inventory_management/blob/main/agent_core.py"
click node_sku "https://github.com/scarwizz/moic_inventory_management/blob/main/sku_store.py"
click node_tools "https://github.com/scarwizz/moic_inventory_management/blob/main/inventory_tools.py"
click node_prep "https://github.com/scarwizz/moic_inventory_management/blob/main/dataprep.py"
click node_aggregation "https://github.com/scarwizz/moic_inventory_management/blob/main/data_aggregation.py"
click node_features "https://github.com/scarwizz/moic_inventory_management/blob/main/feature_engineering.py"
click node_simulation "https://github.com/scarwizz/moic_inventory_management/blob/main/simulation.py"
click node_training "https://github.com/scarwizz/moic_inventory_management/blob/main/train_surrogates.py"
click node_catalogue "https://github.com/scarwizz/moic_inventory_management/blob/main/Dataset/m5_demand_features.csv"
click node_trainingdata "https://github.com/scarwizz/moic_inventory_management/tree/main/Dataset"

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_prep,node_aggregation,node_features,node_simulation,node_catalogue,node_trainingdata toneBlue
class node_training,node_rawdata toneAmber
class node_agent,node_sku,node_tools toneMint
class node_streamlit toneRose
class node_manager,node_groq toneIndigo
```

## Components

### Offline data pipeline

- [Sales preparation](https://github.com/scarwizz/moic_inventory_management/blob/main/dataprep.py): `dataprep.py`
- [Sales aggregation](https://github.com/scarwizz/moic_inventory_management/blob/main/data_aggregation.py): `data_aggregation.py`
- [Demand features](https://github.com/scarwizz/moic_inventory_management/blob/main/feature_engineering.py): `feature_engineering.py`
- [Policy simulation](https://github.com/scarwizz/moic_inventory_management/blob/main/simulation.py): `simulation.py`
- [Demand feature CSV](https://github.com/scarwizz/moic_inventory_management/blob/main/Dataset/m5_demand_features.csv): `Dataset/m5_demand_features.csv`
- [Simulation training data](https://github.com/scarwizz/moic_inventory_management/tree/main/Dataset): `Dataset`

### Surrogate models

- [Surrogate training](https://github.com/scarwizz/moic_inventory_management/blob/main/train_surrogates.py): `train_surrogates.py`

### Agent runtime

- [LangGraph agent](https://github.com/scarwizz/moic_inventory_management/blob/main/agent_core.py): `agent_core.py`
- [SKU profile lookup](https://github.com/scarwizz/moic_inventory_management/blob/main/sku_store.py): `sku_store.py`
- [Policy and cost tools](https://github.com/scarwizz/moic_inventory_management/blob/main/inventory_tools.py): `inventory_tools.py`

### User interface

- [Streamlit dashboard](https://github.com/scarwizz/moic_inventory_management/blob/main/app.py): `app.py`

### Other components

- **Supply manager**
- **Groq Llama model**
- **M5 sales data**

## Connections

- Supply manager → Streamlit dashboard: submits query (evidence: `README.md`)
- Streamlit dashboard → LangGraph agent: invokes agent (evidence: `app.py`)
- LangGraph agent → Groq Llama model: reasons with (evidence: `README.md`)
- LangGraph agent → SKU profile lookup: dispatches lookup (evidence: `agent_core.py`)
- LangGraph agent → Policy and cost tools: dispatches tools (evidence: `agent_core.py`)
- M5 sales data → Sales preparation: reads sales (evidence: `dataprep.py`)
- M5 sales data → Sales aggregation: reads sales (evidence: `data_aggregation.py`)
- Sales aggregation → Demand features: provides series (evidence: `feature_engineering.py`)
- Demand features → Demand feature CSV: writes profiles (evidence: `feature_engineering.py`)
- Demand feature CSV → SKU profile lookup: loads profiles (evidence: `sku_store.py`)
- Demand features → Policy simulation: supplies features (evidence: `simulation.py`)
- Sales aggregation → Policy simulation: supplies sales (evidence: `simulation.py`)
- Policy simulation → Simulation training data: writes targets (evidence: `simulation.py`)
- Simulation training data → Surrogate training: loads observations (evidence: `README.md`)
- Surrogate training → Policy and cost tools: exports predictors (evidence: `README.md`)
- Policy and cost tools → Demand feature CSV: uses demand profile (evidence: `README.md`)
