# gycai-tech/agent-erp architecture

> Architecture diagram of the GitHub repository gycai-tech/agent-erp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gycai-tech/agent-erp
- Repository: https://github.com/gycai-tech/agent-erp

## Overview

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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        UIUser["Usuario"]:::ui
        Streamlit["Streamlit UI<br/>(http://localhost:8501)"]:::ui
        Home["Home (ui/Home.py)"]:::ui
        ChatPage["Chat Page (ui/pages/1_💬_Chat.py)"]:::ui
        APIClient["API Client (ui/utils/api_client.py)"]:::ui
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIServer["FastAPI Server<br/>(app/main.py)"]:::backend
        subgraph "Core"
            direction TB
            Config["Config (app/core/config.py)"]:::backend
            LoggingCore["Logging (app/core/logging.py)"]:::backend
            MonitoringCore["Monitoring (app/core/monitoring.py)"]:::backend
        end
        subgraph "Routes"
            direction TB
            ChatRoute["chat.py"]:::backend
            DBRoute["database.py"]:::backend
            HealthRoute["health.py"]:::backend
            MonRoute["monitoring.py"]:::backend
        end
        subgraph "Schemas"
            direction TB
            ReqSchema["requests.py"]:::backend
            ResSchema["responses.py"]:::backend
        end
        RouterAgent["Router Agent<br/>(Strategy placeholder)"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        SQLServer["SQL Server"]:::db
        Connection["connection.py"]:::db
        Explorer["explorer.py"]:::db
        Qdrant["Qdrant (6333)"]:::db
    end

    %% MCP Module
    subgraph "MCP Module (Phase 2)"
        direction TB
        MCPServer["MCP Server (app/mcp/server.py)"]:::backend
        MCPClient["MCP Client (app/mcp/client.py)"]:::backend
    end

    %% Infra & Scripts
    subgraph "Infra & Scripts"
        direction TB
        ScriptExplore["scripts/explore_database.py"]:::script
        Docs["docs/database_schema.md"]:::script
        DockerfileNode["Dockerfile"]:::script
        Compose["docker-compose.yml"]:::script
    end

    %% Connections
    UIUser --> Streamlit
    Streamlit --> APIClient
    APIClient --> APIServer
    APIServer --> Config
    APIServer --> LoggingCore
    APIServer --> MonitoringCore
    APIServer --> ChatRoute
    APIServer --> DBRoute
    APIServer --> HealthRoute
    APIServer --> MonRoute
    APIServer --> RouterAgent

    RouterAgent --> ChatRoute
    RouterAgent --> MCPServer
    ChatRoute --> Connection
    DBRoute --> Explorer
    Connection --> SQLServer
    MCPServer --> MCPClient
    ScriptExplore --> Docs

    %% Click Events
    click Home "https://github.com/gycai-tech/agent-erp/blob/master/ui/Home.py"
    click ChatPage "https://github.com/gycai-tech/agent-erp/blob/master/ui/pages/1_💬_Chat.py"
    click APIClient "https://github.com/gycai-tech/agent-erp/blob/master/ui/utils/api_client.py"
    click APIServer "https://github.com/gycai-tech/agent-erp/blob/master/app/main.py"
    click ChatRoute "https://github.com/gycai-tech/agent-erp/blob/master/app/api/routes/chat.py"
    click DBRoute "https://github.com/gycai-tech/agent-erp/blob/master/app/api/routes/database.py"
    click HealthRoute "https://github.com/gycai-tech/agent-erp/blob/master/app/api/routes/health.py"
    click MonRoute "https://github.com/gycai-tech/agent-erp/blob/master/app/api/routes/monitoring.py"
    click MCPServer "https://github.com/gycai-tech/agent-erp/blob/master/app/mcp/server.py"
    click MCPClient "https://github.com/gycai-tech/agent-erp/blob/master/app/mcp/client.py"
    click Connection "https://github.com/gycai-tech/agent-erp/blob/master/app/database/connection.py"
    click Explorer "https://github.com/gycai-tech/agent-erp/blob/master/app/database/explorer.py"
    click Config "https://github.com/gycai-tech/agent-erp/blob/master/app/core/config.py"
    click LoggingCore "https://github.com/gycai-tech/agent-erp/blob/master/app/core/logging.py"
    click MonitoringCore "https://github.com/gycai-tech/agent-erp/blob/master/app/core/monitoring.py"
    click ReqSchema "https://github.com/gycai-tech/agent-erp/blob/master/app/schemas/requests.py"
    click ResSchema "https://github.com/gycai-tech/agent-erp/blob/master/app/schemas/responses.py"
    click ScriptExplore "https://github.com/gycai-tech/agent-erp/blob/master/scripts/explore_database.py"
    click DockerfileNode "https://github.com/gycai-tech/agent-erp/tree/master/Dockerfile"
    click Compose "https://github.com/gycai-tech/agent-erp/blob/master/docker-compose.yml"

    %% Styles
    classDef ui fill:#DDEEFF,stroke:#0000CC,color:#000
    classDef backend fill:#DDFFDD,stroke:#008000,color:#000
    classDef db fill:#FFE5CC,stroke:#FF6600,color:#000
    classDef script fill:#F0F0F0,stroke:#888888,color:#000
```
