# rg727876-hub/agentes_automatizaci-n architecture

> Architecture diagram of the GitHub repository rg727876-hub/agentes_automatizaci-n, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rg727876-hub/agentes_automatizaci-n
- Repository: https://github.com/rg727876-hub/agentes_automatizaci-n

## Overview

1. **System shape**
   This repo is a single Python application split into two frontends over the same backend: a browser UI in `frontend/` and a legacy terminal UI in `backend/cli.py`. The operational path is the FastAPI app in `backend/app.py`, which serves both the REST API and the static frontend from one process.

2. **Top-level layering**
   The backend is organized into clear layers: `backend/api/` for HTTP presentation, `backend/agents/` for AI coordination, `backend/tools/` for domain actions and data access, `backend/database/` for PostgreSQL/Supabase setup, and `backend/memory/` for semantic memory. This is a service-style architecture, not a microservice architecture.

3. **Request entry points**
   User interaction starts in the browser through `frontend/static/app.js`, which calls API routes such as `/api/chat`, `/api/dashboard`, `/api/products`, `/api/suppliers`, `/api/history`, `/api/search`, and `/api/health`. The API layer in `backend/api/` is thin and mainly routes requests into shared state, agent orchestration, and database-backed read paths.

4. **Agent core**
   The main business logic lives in the multi-agent layer under `backend/agents/`. `orchestrator.py` is the central router that decides which specialized agent should answer. The specialized agents cover inventory, sales, demand, suppliers, purchasing, and reports. `base.py` provides the common execution loop and tool-calling pattern, so the agents share a uniform interaction model with Gemini.

5. **LLM integration**
   `backend/llm.py` and the agent base layer encapsulate Google Gemini usage. Gemini is used both as the reasoning engine and, per the README, for function/tool calling and embeddings. The architecture therefore depends on external LLM calls for classification, analysis, and generation rather than on local rule engines.

6. **Domain tools boundary**
   The `backend/tools/` package is the main boundary between AI reasoning and operational actions. These modules encapsulate inventory queries, sales analytics, supplier comparison, demand logic, order creation, alerts, and email sending. In diagram terms, the agents decide what to do, while tools perform the concrete business operation against database, email, or internal calculations.

7. **Database and source of truth**
   Supabase/PostgreSQL is the system of record. `backend/database/schema.sql` defines the schema, and `setup.py`, `seed.py`, and `connection.py` manage initialization, seeding, and connections. The repository is designed to auto-create and seed tables on first run, so the database is not just a storage dependency but part of the startup workflow.

8. **Semantic memory**
   Persistent conversational and semantic memory is handled separately in `backend/memory/vector_memory.py`. The README indicates pgvector on Supabase, so memory is not just chat history; it is vector-searchable state used for recall across sessions. This is a distinct data path from operational inventory data and powers `/api/search`, `/api/history`, and memory stats endpoints.

9. **State and lifecycle**
   `backend/api/state.py` is the system composition point: it likely initializes shared objects during FastAPI lifespan and makes them available to routes and agents. This is the main internal boundary for wiring configuration, DB access, memory, and agent instances together. `backend/api/utils.py` appears to provide resilience helpers for failures and retries.

10. **Frontend responsibilities**
   `frontend/index.html`, `styles.css`, and `static/app.js` implement a static dashboard/chat UI with no separate frontend build pipeline. The UI renders KPIs, charts, product/supplier tables, alerts, and the conversational assistant. In architecture terms, the browser is a thin presentation layer that consumes backend JSON and does not own business logic.

11. **Operational flows**
   There are two dominant flows: a read/analytics flow and a conversational/action flow. The dashboard and catalog endpoints read from the PostgreSQL data model and feed charts and tables. The chat endpoint sends the user message to the orchestrator, which may consult memory, route to a specialist agent, call tools, write back to the database, and optionally trigger email for report delivery.

12. **Non-UI execution path**
   `backend/cli.py` exposes the same capabilities in a terminal-first mode, showing that the agent system is reusable outside the web UI. This indicates the backend logic is not coupled to HTTP and can be diagrammed as a core domain engine with multiple interfaces.

13. **Deployment and runtime**
   The project is meant to run as a containerized FastAPI service. `Dockerfile` and `apprunner.yaml` target AWS App Runner, with `/api/health` as the health check. Runtime configuration comes from environment variables in `.env`, especially Gemini, database, and SMTP credentials. `backend/fix_ssl.py` suggests some care for certificate handling in local Windows environments.

14. **What to emphasize in an architecture diagram**
   The key boundaries are: browser UI, FastAPI API, orchestrator/agents, tools, PostgreSQL/Supabase, vector memory, and external services (Gemini and SMTP). The most important arrows are user chat and dashboard requests into FastAPI, FastAPI into the orchestrator or data queries, agents into tools, tools into database/memory/email, and results back to the UI.

Main entry points: [`backend/database/schema.sql`](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/database/schema.sql) (Postgres Core), [`backend/app.py`](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/app.py) (FastAPI App), [`backend/agents/tool_adapter.py`](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/agents/tool_adapter.py) (Tool Adapter), [`backend/api/state.py`](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/api/state.py) (App State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_frontend_ui["Browser UI<br/>static frontend<br/>[app.js]"]
  node_cli_ui["Terminal UI<br/>legacy cli<br/>[cli.py]"]
end

subgraph group_api["API Layer"]
  node_app_server["FastAPI App<br/>web host<br/>[app.py]"]
  node_api_state["App State<br/>composition state<br/>[state.py]"]
  node_api_chat["Chat API<br/>agent endpoint<br/>[chat.py]"]
  node_api_dashboard["Dashboard API<br/>analytics endpoint<br/>[dashboard.py]"]
  node_api_catalog["Catalog API<br/>data endpoint<br/>[catalog.py]"]
  node_api_memory["Memory API<br/>memory endpoint<br/>[memory.py]"]
  node_api_health["Health API<br/>ops endpoint<br/>[health.py]"]
end

subgraph group_agents["Agent Core"]
  node_orchestrator{{"Orchestrator<br/>agent router<br/>[orchestrator.py]"}}
  node_agent_base["Agent Base<br/>execution loop<br/>[base.py]"]
  node_agent_ops["Ops Agents<br/>specialist agents<br/>[inventory.py]"]
  node_tool_adapter["Tool Adapter<br/>agent bridge<br/>[tool_adapter.py]"]
end

subgraph group_tools["Domain Tools"]
  node_inventory_tools["Inventory Tools<br/>business ops<br/>[inventory_tools.py]"]
  node_sales_tools["Sales Tools<br/>analytics ops<br/>[sales_tools.py]"]
  node_supplier_tools["Supplier Tools<br/>procurement ops<br/>[supplier_tools.py]"]
  node_demand_tools["Demand Tools<br/>forecast ops<br/>[demand_tools.py]"]
  node_order_tools["Order Tools<br/>workflow ops<br/>[order_tools.py]"]
  node_alerts_email["Alerts & Email<br/>notifications<br/>[email_tools.py]"]
end

subgraph group_data["Data Layer"]
  node_db_core[("Postgres Core<br/>system of record<br/>[schema.sql]")]
  node_vector_memory[("Vector Memory<br/>semantic memory<br/>[vector_memory.py]")]
end

subgraph group_external["External Services"]
  node_gemini(("Gemini<br/>llm service"))
  node_smtp(("SMTP<br/>mail service"))
end

node_frontend_ui -->|"HTTP requests"| node_app_server
node_cli_ui -->|"direct run"| node_orchestrator
node_app_server -->|"wires state"| node_api_state
node_app_server -->|"routes"| node_api_chat
node_app_server -->|"routes"| node_api_dashboard
node_app_server -->|"routes"| node_api_catalog
node_app_server -->|"routes"| node_api_memory
node_app_server -->|"routes"| node_api_health
node_api_chat -->|"dispatch"| node_orchestrator
node_api_dashboard -->|"reads"| node_db_core
node_api_catalog -->|"reads"| node_db_core
node_api_memory -->|"searches"| node_vector_memory
node_api_state -->|"provides"| node_orchestrator
node_api_state -->|"provides"| node_db_core
node_api_state -->|"provides"| node_vector_memory
node_api_state -->|"provides"| node_gemini
node_orchestrator -->|"uses"| node_agent_base
node_orchestrator -->|"routes to"| node_agent_ops
node_agent_base -->|"calls"| node_gemini
node_agent_ops -->|"invokes"| node_tool_adapter
node_tool_adapter -->|"bridges"| node_inventory_tools
node_tool_adapter -->|"bridges"| node_sales_tools
node_tool_adapter -->|"bridges"| node_supplier_tools
node_tool_adapter -->|"bridges"| node_demand_tools
node_tool_adapter -->|"bridges"| node_order_tools
node_tool_adapter -->|"bridges"| node_alerts_email
node_inventory_tools -->|"writes/reads"| node_db_core
node_sales_tools -->|"reads"| node_db_core
node_supplier_tools -->|"reads"| node_db_core
node_demand_tools -->|"reads"| node_db_core
node_order_tools -->|"writes"| node_db_core
node_alerts_email -->|"sends"| node_smtp
node_vector_memory -->|"stores on"| node_db_core

click node_frontend_ui "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/frontend/static/app.js"
click node_cli_ui "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/cli.py"
click node_app_server "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/app.py"
click node_api_state "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/api/state.py"
click node_api_chat "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/api/chat.py"
click node_api_dashboard "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/api/dashboard.py"
click node_api_catalog "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/api/catalog.py"
click node_api_memory "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/api/memory.py"
click node_api_health "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/api/health.py"
click node_orchestrator "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/agents/orchestrator.py"
click node_agent_base "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/agents/base.py"
click node_agent_ops "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/agents/inventory.py"
click node_tool_adapter "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/agents/tool_adapter.py"
click node_inventory_tools "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/tools/inventory_tools.py"
click node_sales_tools "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/tools/sales_tools.py"
click node_supplier_tools "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/tools/supplier_tools.py"
click node_demand_tools "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/tools/demand_tools.py"
click node_order_tools "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/tools/order_tools.py"
click node_alerts_email "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/tools/email_tools.py"
click node_db_core "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/database/schema.sql"
click node_vector_memory "https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/memory/vector_memory.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_ui,node_cli_ui toneBlue
class node_app_server,node_api_state,node_api_chat,node_api_dashboard,node_api_catalog,node_api_memory,node_api_health toneAmber
class node_orchestrator,node_agent_base,node_agent_ops,node_tool_adapter toneMint
class node_inventory_tools,node_sales_tools,node_supplier_tools,node_demand_tools,node_order_tools,node_alerts_email toneRose
class node_db_core,node_vector_memory toneIndigo
class node_gemini,node_smtp toneTeal
```

## Components

### Presentation

Browser and terminal entry points

- [Browser UI](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/frontend/static/app.js): static frontend · Single-page dashboard and chat UI · `frontend/static/app.js`
- [Terminal UI](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/cli.py): legacy cli · Command-line entry point for the same backend capabilities · `backend/cli.py`

### API Layer

FastAPI routes and shared app state

- [FastAPI App](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/app.py): web host · Main process that serves API routes and static frontend · `backend/app.py`
- [App State](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/api/state.py): composition state · Wires shared dependencies and lifecycle-managed objects · `backend/api/state.py`
- [Chat API](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/api/chat.py): agent endpoint · Routes conversational requests into orchestration · `backend/api/chat.py`
- [Dashboard API](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/api/dashboard.py): analytics endpoint · Serves dashboard KPIs and summary reads · `backend/api/dashboard.py`
- [Catalog API](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/api/catalog.py): data endpoint · Exposes product and supplier read paths · `backend/api/catalog.py`
- [Memory API](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/api/memory.py): memory endpoint · Search and history access for semantic recall · `backend/api/memory.py`
- [Health API](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/api/health.py): ops endpoint · Liveness and readiness check · `backend/api/health.py`

### Agent Core

Orchestration and specialized AI agents

- [Orchestrator](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/agents/orchestrator.py): agent router · Chooses the right specialist agent and manages the conversation flow · `backend/agents/orchestrator.py`
- [Agent Base](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/agents/base.py): execution loop · Shared Gemini tool-calling and run loop for agents · `backend/agents/base.py`
- [Ops Agents](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/agents/inventory.py): specialist agents · Inventory, sales, demand, suppliers, purchasing, and reports agents · `backend/agents/inventory.py`
- [Tool Adapter](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/agents/tool_adapter.py): agent bridge · Connects agent calls to concrete tool modules · `backend/agents/tool_adapter.py`

### Domain Tools

Operational actions and business logic

- [Inventory Tools](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/tools/inventory_tools.py): business ops · Inventory queries and operational checks · `backend/tools/inventory_tools.py`
- [Sales Tools](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/tools/sales_tools.py): analytics ops · Sales analysis and metrics helpers · `backend/tools/sales_tools.py`
- [Supplier Tools](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/tools/supplier_tools.py): procurement ops · Supplier comparison and sourcing helpers · `backend/tools/supplier_tools.py`
- [Demand Tools](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/tools/demand_tools.py): forecast ops · Demand logic and planning calculations · `backend/tools/demand_tools.py`
- [Order Tools](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/tools/order_tools.py): workflow ops · Order creation and purchasing actions · `backend/tools/order_tools.py`
- [Alerts & Email](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/tools/email_tools.py): notifications · Alert monitoring and outbound email delivery · `backend/tools/email_tools.py`

### Data Layer

Database and semantic memory

- [Postgres Core](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/database/schema.sql): system of record · Schema, setup, seed, and connection workflow for Supabase/PostgreSQL · `backend/database/schema.sql`
- [Vector Memory](https://github.com/rg727876-hub/agentes_automatizaci-n/blob/main/backend/memory/vector_memory.py): semantic memory · Persistent searchable memory built on pgvector · `backend/memory/vector_memory.py`

### External Services

LLM and outbound integrations

- **Gemini**: llm service · Reasoning, tool calling, and embeddings provider
- **SMTP**: mail service · Outbound email channel for reports and alerts

## Connections

- Browser UI → FastAPI App: HTTP requests · Browser calls API endpoints for chat, dashboard, catalog, and memory
- Terminal UI → Orchestrator: direct run · Terminal mode reaches the same agent core without HTTP
- FastAPI App → App State: wires state · FastAPI composition and lifecycle setup
- FastAPI App → Chat API: routes · Chat requests enter the API layer
- FastAPI App → Dashboard API: routes · Dashboard requests enter the API layer
- FastAPI App → Catalog API: routes · Catalog reads enter the API layer
- FastAPI App → Memory API: routes · Search and history requests enter the API layer
- FastAPI App → Health API: routes · Health check endpoint
- Chat API → Orchestrator: dispatch · Conversation is handed to the agent router
- Dashboard API → Postgres Core: reads · Dashboard aggregates operational data
- Catalog API → Postgres Core: reads · Catalog endpoints query the system of record
- Memory API → Vector Memory: searches · History and recall come from semantic memory
- App State → Orchestrator: provides · Shared agent instances and configuration
- App State → Postgres Core: provides · Database access is shared through app state
- App State → Vector Memory: provides · Memory service is shared through app state
- App State → Gemini: provides · LLM client is initialized in shared state
- Orchestrator → Agent Base: uses · Specialized agents share the common execution model
- Orchestrator → Ops Agents: routes to · Chooses the appropriate specialist agent
- Agent Base → Gemini: calls · Reasoning and tool calling depend on Gemini
- Ops Agents → Tool Adapter: invokes · Specialist agents delegate concrete actions
- Tool Adapter → Inventory Tools: bridges · Inventory operations
- Tool Adapter → Sales Tools: bridges · Sales analysis operations
- Tool Adapter → Supplier Tools: bridges · Supplier comparison operations
- Tool Adapter → Demand Tools: bridges · Demand planning operations
- Tool Adapter → Order Tools: bridges · Ordering and purchasing operations
- Tool Adapter → Alerts & Email: bridges · Alerts and outbound messages
- Inventory Tools → Postgres Core: writes/reads · Operational inventory actions use the database
- Sales Tools → Postgres Core: reads · Sales analytics are sourced from the database
- Supplier Tools → Postgres Core: reads · Supplier data comes from the database
- Demand Tools → Postgres Core: reads · Demand logic uses persisted data
- Order Tools → Postgres Core: writes · Order creation persists back to the database
- Alerts & Email → SMTP: sends · Emails and notifications leave the system through SMTP
- Vector Memory → Postgres Core: stores on · Semantic memory is persisted in PostgreSQL/Supabase