How gycai-tech/agent-erp works
Para dibujar el diagrama de arquitectura más preciso para el proyecto “Agente ERP – Sistema Híbrido de Consultas”, sigue estos pasos:
Identifica el tipo y propósito del proyecto
• Se trata de una aplicación full-stack Python + Streamlit cuyo objetivo es:
• Explorar y documentar un esquema de base de datos ERP
• Responder consultas en lenguaje natural
• Decidir entre rutas de consulta REST (para consultas frecuentes) y MCP (para consultas complejas)
• Monitorizar uso y generar documentación
Componentes principales (diagrama de alto nivel)
• Usuario
• Interfaz de usuario (Streamlit UI)
• Servidor de API (FastAPI)
• Agente Router (decide API vs MCP)
• Módulo API REST
• Módulo MCP (Model Context Protocol) – fase 2
• Base de datos SQL Server
• Motor de vectores (Qdrant en Docker Compose, fase 2+/embeddings)
• Sistema de monitoring/logging
• Script de exploración (scripts/explore_database.py)
• Documentación generada (docs/database_schema.md)
Relaciones e interacción
• El usuario accede a la UI Streamlit (http://localhost:8501)
• La UI invoca al API Client (ui/utils/api_client.py) y llama endpoints de FastAPI
• FastAPI (app/main.py) recibe peticiones y las enruta:
a. A los endpoints REST en app/api/routes/*
b. Al “Router Agent” (lógica en fase 2) para decidir entre API REST y MCP
• API REST (app/api/routes/chat.py, database.py, monitoring.py, health.py)
→ Conecta a app/database/connection.py para ejecutar consultas SQL
→ Usa app/database/explorer.py para explorar esquema
• MCP Server (app/mcp/server.py & client.py)
→ Para consultas complejas: interacción con modelos externos (Groq/Claude)
• Logging y Monitoring (app/core/logging.py, monitoring.py)
→ Registra métricas de uso, estadísticas, errores
• Script de exploración (scripts/explore_database.py)
→ Se ejecuta off-line para generar docs/database_schema.md
• Docker Compose orquesta:
• FastAPI
• Streamlit UI
• Qdrant (vector store)
Patrón Arquitectónico
• Full-stack con separación UI / API / DB
• Microservicios ligeros: FastAPI para REST; módulo MCP independiente
• Agente Router (próximas fases) aplica patrón Strategy
• Configuración central en app/core/config.py
• Modelado de datos con Pydantic (app/schemas)
Cómo dibujarlo
a. Dibuja rectángulos para cada gran bloque:
[Usuario] → [Streamlit UI] → [FastAPI] → {Router Agent} → {API REST│MCP Server│SQL Server}
b. Usa flechas unidireccionales para flujos de petición/respuesta
c. Colorea:
• UI (azul)
• Backend/API (verde)
• Base de datos y vector store (naranja)
• Scripts/documentación (gris)
d. Agrega anotaciones:
• Puerto y URLs (8501 UI, 8000 API, 6333 Qdrant)
• Componentes de core (config, logging, monitoring) junto al API
Detalle del diagrama
• Capa UI:
• ui/Home.py, ui/pages, api_client
• Capa API:
• app/main.py
• app/api/routes/*.py
• app/core (config, logging, monitoring)
• app/schemas (requests, responses)
• Capa de Datos:
• app/database/connection.py (pool ODBC)
• app/database/explorer.py
• SQL Server (externo)
• Capa MCP (Fase 2):
• app/mcp/server.py
• app/mcp/client.py
• Orquestación/Infra:
• Dockerfile, docker-compose.yml
• scripts/explore_database.py → docs/database_schema.md
Pautas para el ingeniero
• Cada componente en un bloque claramente etiquetado
• Flechas con dirección para mostrar llamadas HTTP o conexiones DB
• Leyenda de colores/íconos para UI, backend, data store, external services
• Indicar dependencias (p.ej. Pydantic para validación, Streamlit para UI)
• Incluir notas sobre la fase de desarrollo (qué está implementado y qué es roadmap)
Con este nivel de detalle tendrás un diagrama que refleja la estructura actual y sirve de base para las fases futuras de MCP, agentes y embeddings.