How rg727876-hub/agentes_automatizaci-n works
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: schema.sql Postgres Core · app.py FastAPI App · tool_adapter.py Tool Adapter · state.py App State
Components 23
Presentation
Browser and terminal entry points
- Browser UI · Single-page dashboard and chat UI
frontend/static/app.js - Terminal UI · Command-line entry point for the same backend capabilities
backend/cli.py
API Layer
FastAPI routes and shared app state
- FastAPI App · Main process that serves API routes and static frontend
backend/app.py - App State · Wires shared dependencies and lifecycle-managed objects
backend/api/state.py - Chat API · Routes conversational requests into orchestration
backend/api/chat.py - Dashboard API · Serves dashboard KPIs and summary reads
backend/api/dashboard.py - Catalog API · Exposes product and supplier read paths
backend/api/catalog.py - Memory API · Search and history access for semantic recall
backend/api/memory.py - Health API · Liveness and readiness check
backend/api/health.py
Agent Core
Orchestration and specialized AI agents
- Orchestrator · Chooses the right specialist agent and manages the conversation flow
backend/agents/orchestrator.py - Agent Base · Shared Gemini tool-calling and run loop for agents
backend/agents/base.py - Ops Agents · Inventory, sales, demand, suppliers, purchasing, and reports agents
backend/agents/inventory.py - Tool Adapter · Connects agent calls to concrete tool modules
backend/agents/tool_adapter.py
Domain Tools
Operational actions and business logic
- Inventory Tools · Inventory queries and operational checks
backend/tools/inventory_tools.py - Sales Tools · Sales analysis and metrics helpers
backend/tools/sales_tools.py - Supplier Tools · Supplier comparison and sourcing helpers
backend/tools/supplier_tools.py - Demand Tools · Demand logic and planning calculations
backend/tools/demand_tools.py - Order Tools · Order creation and purchasing actions
backend/tools/order_tools.py - Alerts & Email · Alert monitoring and outbound email delivery
backend/tools/email_tools.py
Data Layer
Database and semantic memory
- Postgres Core · Schema, setup, seed, and connection workflow for Supabase/PostgreSQL
backend/database/schema.sql - Vector Memory · Persistent searchable memory built on pgvector
backend/memory/vector_memory.py
External Services
LLM and outbound integrations
- Gemini · Reasoning, tool calling, and embeddings provider
- SMTP · Outbound email channel for reports and alerts
Connections 33
- 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