# ddelgadillod/inventaio architecture

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

- Interactive diagram: https://gitdiagram.com/ddelgadillod/inventaio
- Repository: https://github.com/ddelgadillod/inventaio

## Overview

InventAI/o is an analytics and decision-support product for grocery distributors: users sign in to the web app, inspect inventory, alerts and reports, and request forecasts and purchasing or transfer recommendations; Vera provides read-only conversational access. The Core API enforces authentication and role-based access while serving analytical queries and coordinating ML and chat services. ETL loads the star-schema warehouse, and the ML service computes forecasts and recommendations from it. Edges follow the README and cited source references; some internals are unsampled, so those relationships are left out or marked unverified.

Main entry points: [`api/main.py`](https://github.com/ddelgadillod/inventaio/blob/main/api/main.py) (Core API routing), [`api/core/database.py`](https://github.com/ddelgadillod/inventaio/blob/main/api/core/database.py) (Star-schema warehouse), [`ml_service/main.py`](https://github.com/ddelgadillod/inventaio/blob/main/ml_service/main.py) (ML service), [`ml_service/prediccion/servicio.py`](https://github.com/ddelgadillod/inventaio/blob/main/ml_service/prediccion/servicio.py) (Demand forecasts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_frontend["Web screens<br/>[App.jsx]"]
  node_webchat["Chat interface<br/>[PanelChat.jsx]"]
end

subgraph group_core["Core API"]
  node_auth["Authentication and roles<br/>[dependencies.py]"]
  node_api["Core API routing<br/>[main.py]"]
  node_inventory["Inventory queries<br/>[router.py]"]
  node_catalog["Catalog queries<br/>[router.py]"]
  node_alerts["Rule and AI alerts<br/>[router.py]"]
  node_reports["Reports and KPIs<br/>[router.py]"]
  node_recommendations["Recommendation API<br/>[router.py]"]
  node_chatgateway["Chat gateway<br/>[router.py]"]
end

subgraph group_ml["Forecasting and recommendations"]
  node_mlservice["ML service<br/>[main.py]"]
  node_forecast["Demand forecasts<br/>[servicio.py]"]
  node_purchase["Purchase recommendations<br/>[motor.py]"]
  node_transfers["Transfer recommendations<br/>[motor.py]"]
  node_mlwarehouse[("ML warehouse access<br/>[bodega.py]")]
end

subgraph group_vera["Vera assistant"]
  node_agent["Agent orchestration<br/>[bucle.py]"]
  node_tools["Read-only tools<br/>[catalogo.py]"]
  node_llm["Local language model<br/>[cliente.py]"]
end

subgraph group_data["Analytical data"]
  node_etl["Real-data ETL<br/>[cargar_postgres.py]"]
  node_warehouse[("Star-schema warehouse<br/>[database.py]")]
end

node_user(("Distributor user"))

node_user -->|"uses"| node_frontend
node_frontend -->|"calls"| node_api
node_frontend -->|"opens"| node_webchat
node_webchat -->|"streams chat"| node_chatgateway
node_api -->|"applies auth"| node_auth
node_api -->|"routes to"| node_inventory
node_api -->|"routes to"| node_catalog
node_api -->|"routes to"| node_alerts
node_api -->|"routes to"| node_reports
node_api -->|"routes to"| node_recommendations
node_api -->|"routes to"| node_chatgateway
node_inventory -->|"queries"| node_warehouse
node_catalog -->|"queries"| node_warehouse
node_alerts -->|"queries"| node_warehouse
node_reports -->|"queries"| node_warehouse
node_recommendations -->|"requests results"| node_mlservice
node_mlservice -->|"initializes"| node_forecast
node_mlservice -->|"serves"| node_purchase
node_mlservice -->|"serves"| node_transfers
node_forecast -.->|"uses warehouse"| node_mlwarehouse
node_purchase -->|"uses forecasts"| node_forecast
node_transfers -->|"uses forecasts"| node_forecast
node_mlwarehouse -.->|"reads"| node_warehouse
node_etl -->|"loads data"| node_warehouse
node_chatgateway -->|"forwards stream"| node_agent
node_agent -.->|"dispatches tools"| node_tools
node_agent -.->|"uses model"| node_llm
node_tools -->|"queries Core API"| node_api

click node_frontend "https://github.com/ddelgadillod/inventaio/blob/main/frontend/src/App.jsx"
click node_webchat "https://github.com/ddelgadillod/inventaio/blob/main/frontend/src/components/chat/PanelChat.jsx"
click node_auth "https://github.com/ddelgadillod/inventaio/blob/main/api/auth/dependencies.py"
click node_api "https://github.com/ddelgadillod/inventaio/blob/main/api/main.py"
click node_inventory "https://github.com/ddelgadillod/inventaio/blob/main/api/inventario/router.py"
click node_catalog "https://github.com/ddelgadillod/inventaio/blob/main/api/consulta/router.py"
click node_alerts "https://github.com/ddelgadillod/inventaio/blob/main/api/alertas/router.py"
click node_reports "https://github.com/ddelgadillod/inventaio/blob/main/api/reportes/router.py"
click node_recommendations "https://github.com/ddelgadillod/inventaio/blob/main/api/ml/router.py"
click node_chatgateway "https://github.com/ddelgadillod/inventaio/blob/main/api/chat/router.py"
click node_mlservice "https://github.com/ddelgadillod/inventaio/blob/main/ml_service/main.py"
click node_forecast "https://github.com/ddelgadillod/inventaio/blob/main/ml_service/prediccion/servicio.py"
click node_purchase "https://github.com/ddelgadillod/inventaio/blob/main/ml_service/compras/motor.py"
click node_transfers "https://github.com/ddelgadillod/inventaio/blob/main/ml_service/transferencias/motor.py"
click node_agent "https://github.com/ddelgadillod/inventaio/blob/main/nlp_agent/agente/bucle.py"
click node_tools "https://github.com/ddelgadillod/inventaio/blob/main/nlp_agent/herramientas/catalogo.py"
click node_llm "https://github.com/ddelgadillod/inventaio/blob/main/nlp_agent/llm/cliente.py"
click node_etl "https://github.com/ddelgadillod/inventaio/blob/main/etl_real/cargar_postgres.py"
click node_warehouse "https://github.com/ddelgadillod/inventaio/blob/main/api/core/database.py"
click node_mlwarehouse "https://github.com/ddelgadillod/inventaio/blob/main/ml_service/prediccion/bodega.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_frontend,node_webchat,node_user toneBlue
class node_auth,node_api,node_inventory,node_catalog,node_alerts,node_reports,node_recommendations,node_chatgateway toneAmber
class node_mlservice,node_forecast,node_purchase,node_transfers,node_mlwarehouse toneMint
class node_agent,node_tools,node_llm toneRose
class node_etl,node_warehouse toneIndigo
```

## Components

### Web application

- [Web screens](https://github.com/ddelgadillod/inventaio/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat interface](https://github.com/ddelgadillod/inventaio/blob/main/frontend/src/components/chat/PanelChat.jsx): `frontend/src/components/chat/PanelChat.jsx`

### Core API

- [Authentication and roles](https://github.com/ddelgadillod/inventaio/blob/main/api/auth/dependencies.py): `api/auth/dependencies.py`
- [Core API routing](https://github.com/ddelgadillod/inventaio/blob/main/api/main.py): `api/main.py`
- [Inventory queries](https://github.com/ddelgadillod/inventaio/blob/main/api/inventario/router.py): `api/inventario/router.py`
- [Catalog queries](https://github.com/ddelgadillod/inventaio/blob/main/api/consulta/router.py): `api/consulta/router.py`
- [Rule and AI alerts](https://github.com/ddelgadillod/inventaio/blob/main/api/alertas/router.py): `api/alertas/router.py`
- [Reports and KPIs](https://github.com/ddelgadillod/inventaio/blob/main/api/reportes/router.py): `api/reportes/router.py`
- [Recommendation API](https://github.com/ddelgadillod/inventaio/blob/main/api/ml/router.py): `api/ml/router.py`
- [Chat gateway](https://github.com/ddelgadillod/inventaio/blob/main/api/chat/router.py): `api/chat/router.py`

### Forecasting and recommendations

- [ML service](https://github.com/ddelgadillod/inventaio/blob/main/ml_service/main.py): `ml_service/main.py`
- [Demand forecasts](https://github.com/ddelgadillod/inventaio/blob/main/ml_service/prediccion/servicio.py): `ml_service/prediccion/servicio.py`
- [Purchase recommendations](https://github.com/ddelgadillod/inventaio/blob/main/ml_service/compras/motor.py): `ml_service/compras/motor.py`
- [Transfer recommendations](https://github.com/ddelgadillod/inventaio/blob/main/ml_service/transferencias/motor.py): `ml_service/transferencias/motor.py`
- [ML warehouse access](https://github.com/ddelgadillod/inventaio/blob/main/ml_service/prediccion/bodega.py): `ml_service/prediccion/bodega.py`

### Vera assistant

- [Agent orchestration](https://github.com/ddelgadillod/inventaio/blob/main/nlp_agent/agente/bucle.py): `nlp_agent/agente/bucle.py`
- [Read-only tools](https://github.com/ddelgadillod/inventaio/blob/main/nlp_agent/herramientas/catalogo.py): `nlp_agent/herramientas/catalogo.py`
- [Local language model](https://github.com/ddelgadillod/inventaio/blob/main/nlp_agent/llm/cliente.py): `nlp_agent/llm/cliente.py`

### Analytical data

- [Real-data ETL](https://github.com/ddelgadillod/inventaio/blob/main/etl_real/cargar_postgres.py): `etl_real/cargar_postgres.py`
- [Star-schema warehouse](https://github.com/ddelgadillod/inventaio/blob/main/api/core/database.py): `api/core/database.py`

### Other components

- **Distributor user**

## Connections

- Distributor user → Web screens: uses (evidence: `README.md`)
- Web screens → Core API routing: calls (evidence: `README.md`)
- Web screens → Chat interface: opens (evidence: `frontend/src/App.jsx`)
- Chat interface → Chat gateway: streams chat (evidence: `README.md`)
- Core API routing → Authentication and roles: applies auth (evidence: `api/main.py`)
- Core API routing → Inventory queries: routes to (evidence: `api/main.py`)
- Core API routing → Catalog queries: routes to (evidence: `api/main.py`)
- Core API routing → Rule and AI alerts: routes to (evidence: `api/main.py`)
- Core API routing → Reports and KPIs: routes to (evidence: `api/main.py`)
- Core API routing → Recommendation API: routes to (evidence: `api/main.py`)
- Core API routing → Chat gateway: routes to (evidence: `api/main.py`)
- Inventory queries → Star-schema warehouse: queries (evidence: `api/inventario/router.py`)
- Catalog queries → Star-schema warehouse: queries (evidence: `api/consulta/router.py`)
- Rule and AI alerts → Star-schema warehouse: queries (evidence: `api/alertas/router.py`)
- Reports and KPIs → Star-schema warehouse: queries (evidence: `api/reportes/router.py`)
- Recommendation API → ML service: requests results (evidence: `api/ml/router.py`)
- ML service → Demand forecasts: initializes (evidence: `ml_service/main.py`)
- ML service → Purchase recommendations: serves (evidence: `ml_service/main.py`)
- ML service → Transfer recommendations: serves (evidence: `ml_service/main.py`)
- Demand forecasts → ML warehouse access: uses warehouse
- Purchase recommendations → Demand forecasts: uses forecasts
- Transfer recommendations → Demand forecasts: uses forecasts (evidence: `ml_service/transferencias/motor.py`)
- ML warehouse access → Star-schema warehouse: reads
- Real-data ETL → Star-schema warehouse: loads data (evidence: `README.md`)
- Chat gateway → Agent orchestration: forwards stream (evidence: `api/chat/router.py`)
- Agent orchestration → Read-only tools: dispatches tools
- Agent orchestration → Local language model: uses model
- Read-only tools → Core API routing: queries Core API (evidence: `README.md`)
