Plataforma jg :: Visión General y Arquitectura Global

Arquitectura técnica de la plataforma: agentes inteligentes autónomos en Python, panel de administración con supervisión humana y plugins extensibles.

1. Visión Holística del Sistema

La Plataforma jg es una solución de arquitectura de software diseñada para operar sistemas de agentes inteligentes en entornos empresariales de misión crítica. Resuelve la brecha estructural entre los modelos probabilísticos (LLMs) y los requisitos de predictibilidad, seguridad, gobernanza corporativa e integración con infraestructuras heterogéneas:

 ┌─────────────────────────────────────────────────────────────────────────────────────────┐
 │                   SISTEMAS EXTERNOS, CLIENTES E INFRAESTRUCTURAS                        │
 └──────────────┬──────────────────────────────────────────────────────────┬───────────────┘
                │                                                          │
                │ Peticiones Heterogéneas                                  │ Peticiones Canónicas
                │ (CI/CD Webhooks, Asterisk PBX / Voz, Chatbots)           │ (AgentInput + HMAC-SHA256)
                ▼                                                          │
 ┌──────────────────────────────────────────────────────────────────────┐  │
 │          PLANO DE CONTROL Y PASARELA DE I/O: jg_dashboard            │  │
 │         Laravel 11 · Filament v3 · Livewire 3 · PostgreSQL           │  │
 │                                                                      │  │
 │  ┌──────────────────────────────┐  ┌──────────────────────────────┐  │  │
 │  │ Gobernanza y Control (HITL)  │  │ Pasarela de I/O (Adapters)   │  │  │
 │  │ - Inventario y telemetría    │  │ - InputNormalizer            │  │  │
 │  │ - lockForUpdate pesimista    │  │ - ClientOutputFormatter      │  │  │
 │  │ - Auditoría y roles RBAC     │  │ - HttpWebhook & MockAsterisk │  │  │
 │  └──────────────────────────────┘  └──────────────────────────────┘  │  │
 └──────────────────────────────────┬───────────────────────────────────┘  │
                                    │                                      │
                                    │ Firma HMAC canónica interna          │
                                    ▼                                      ▼
 ┌─────────────────────────────────────────────────────────────────────────────────────────┐
 │                       PLANO DE EJECUCIÓN: jg_agente (Python 3.12)                       │
 │                  LangGraph · FastAPI · SecurityGuard · DualPostgresSaver                │
 └──────────────────────────┬───────────────────────────────┬──────────────────────────────┘
                            │                               │
               ┌────────────┴────────────────┐ ┌────────────┴────────────────┐
               ▼                             ▼ ▼                             ▼
        [Plugin Conversacional]     [Plugin DevOps / SRE]        [Plugin Datos.gob.es]
        (Atención y Clima)          (Diagnóstico de Infra)       (Catálogo Open Data)

1.1 Principios Rectores

1. Desacoplamiento Estricto de Responsabilidades: Separación física y lógica entre el Plano de Control y Pasarela (PHP/Laravel para interfaz, auditoría, autorización humana, roles RBAC y normalización de estímulos externos) y el Plano de Ejecución (Python/FastAPI para ejecución autónoma de grafos LangGraph y razonamiento con LLMs). El agente puede operar de manera 100% autónoma sin depender de una consola gráfica.
2. Doble Topología de Integración (Directa vs Pasarela Heterogénea):
   • Vía Canónica Directa: Clientes y microservicios con soporte nativo de contratos (AgentInput) y firma HMAC pueden invocar directamente al agente (POST /executions/trigger), asegurando máxima velocidad y cero intermediación.
   • Vía Pasarela Inteligente (jg_dashboard): Infraestructuras heterogéneas que no hablan el contrato canónico (disparadores de CI/CD de GitLab/GitHub, telefonía Asterisk PBX, bots de mensajería) entran a través de los adaptadores de jg_dashboard, que absorben la complejidad de formato, interponen firmas de seguridad y aplican gobernanza humana unificada.
3. Reversibilidad y Determinismo Transaccional: Cada paso de razonamiento y ejecución de herramientas es inmutable y versionado con checkpointing atómico en PostgreSQL (DualPostgresSaver con vistas canónicas core_checkpoints*), permitiendo compensación inversa (tool.rollback()).
4. Gobernanza Human-in-the-Loop (HITL) Obligatoria: Las operaciones de alto impacto (RiskLevel >= HIGH) se interrumpen automáticamente esperando autorización explícita con control de concurrencia pesimista (lockForUpdate).
5. Ecosistema de Plugins Modulares: El núcleo es agnóstico a la lógica de negocio; todas las capacidades operativas se instancian a través de plugins empaquetados e instalables con el SDK canónico (jg_agente_sdk).
6. Invarianza de Seguridad Zero-Trust: Las directivas de seguridad (anti-SSRF, inyección de comandos, path traversal y contención de red) no pueden ser eludidas ni siquiera por usuarios con rol administrativo (AGENTE-SEC-06).

2. Modos de Funcionamiento y Topologías Operativas

El ecosistema soporta cuatro modalidades principales adaptadas al grado de heterogeneidad del entorno:

1. Modo Pasarela Heterogénea / Proxy de I/O (jg_dashboard):
   Entornos externos dispares (GitLab CI/CD, eventos GitHub, centralitas Asterisk PBX / IVR de voz, mensajería empresarial) envían sus estímulos a los endpoints de adaptación del Dashboard (/api/v1/adapters/webhook, /api/v1/adapters/mock-asterisk). InputNormalizer sintetiza la petición a AgentInput, gestiona la sesión, delega la ejecución al agente firmando con HMAC y retorna la respuesta serializada al formato del cliente (ClientOutputFormatter).
2. Modo Invocación Canónica Directa (Nativa / SDK):
   Invocado directamente por aplicaciones cliente o microservicios que utilicen el SDK jg_agente_sdk (JgAgenteClient). El llamante construye AgentInput, firma con su clave permanente (X-JG-Signature, X-JG-Timestamp) y procesa directamente AgentOutput. jg_agente opera de forma completamente autónoma sin requerir el Dashboard.
3. Modo Clúster Gestionado y Gobernanza:
   Enrolado dinámicamente mediante Bootstrap Tokens de un solo uso (TTL 24h) en consolas de gobernanza como jg_dashboard. Emite heartbeats periódicos cada 30 segundos, sincroniza su catálogo de capacidades y delega la interfaz HITL en paneles web.
4. Modo Desconectado / Local (CI/CD):
   Ejecución en memoria (CHECKPOINT_SAVER=memory) con modelos cognitivos simulados (LLM_PROVIDER=mock) para desarrollo ágil y pipelines de prueba automatizados sin dependencias externas.

3. Topología C4: Modelado de Arquitectura

3.1 Diagrama de Contexto del Sistema (C4 - Nivel 1)

+-----------------------------------------------------------------------------------+
|                               CONTEXTO DE SISTEMA                                 |
+-----------------------------------------------------------------------------------+

     [Operador / Auditor HITL]    [Entornos Heterogéneos: CI/CD, PBX, Chat]     [Clientes SDK / Nativos]
                 │                                    │                                    │
                 │ (Web UI HTTPS)                     │ (Webhooks / REST / Audio)          │ (AgentInput + HMAC)
                 ▼                                    ▼                                    │
    ┌────────────────────────────────────────────────────────┐                             │
    │                      jg_dashboard                      │                             │
    │  Control Plane, Gobernanza HITL & Pasarela de I/O      │                             │
    │  - Normalizador de Estímulos (InputNormalizer)         │                             │
    │  - Serializador Multicanal (ClientOutputFormatter)     │                             │
    │  - Firmas HMAC-SHA256 (AgentHttpClient)                │                             │
    └───────────────────────────┬────────────────────────────┘                             │
                                │                                                          │
                                │ Firmas HMAC-SHA256 (Red Privada)                         │
                                ▼                                                          ▼
    ┌──────────────────────────────────────────────────────────────────────────────────────┐
    │                             jg_agente (Execution Plane)                              │
    │                 Runtime Autónomo LangGraph + FastAPI en Python 3.12                  │
    └───────────────────────────┬────────────────────────────┬─────────────────────────────┘
                                │                            │
                                │ DNS Pinning + SSRF Guard   │ Docker API Restringido
                                ▼                            ▼
                   ┌──────────────────────────┐ ┌──────────────────────────┐
                   │ Fuentes Externas / APIs  │ │   Infraestructura Host   │
                   │(Datos.gob.es, LLMs Groq) │ │  (Daemon, Contenedores)  │
                   └──────────────────────────┘ └──────────────────────────┘

3.2 Diagrama de Contenedores y Red (C4 - Nivel 2)

+----------------------------------------------------------------------------------------+
|                      CONTENEDORES DE LA PLATAFORMA jg                                  |
+----------------------------------------------------------------------------------------+

 [Operadores / Consola Web]       [Entornos Heterogéneos: Webhook, Asterisk]    [Clientes SDK Canónicos]
            │                                         │                                    │
            │ HTTPS (:8080)                           │ HTTP/REST                          │ HTTP + HMAC-SHA256
            ▼                                         ▼                                    │
 ┌──────────────────────────────────────────────────────────────────────┐                  │
 │                      jg_dashboard (:8080)                            │                  │
 │  Laravel 11 · Filament v3 · Livewire 3                               │                  │
 │  - Subsistema App\Adapters (Webhooks, Asterisk, Formatter)           │                  │
 │  - Panel HITL y Control Plane                                        │                  │
 └──────────────┬─────────────────────────────────────┬─────────────────┘                  │
                │                                     │                                    │
                ├─────────────────────┐               │ Red Docker Privada                 │
                ▼                     ▼               │ (jg_network_prod)                  │
 ┌──────────────────────────────┐     │               │                                    │
 │    jg_dashboard_postgres     │     │               ▼                                    ▼
 │    Base de datos (:5434)     │     │    ┌────────────────────────────────────────────────────────┐
 └──────────────────────────────┘     │    │             PLANO DE EJECUCIÓN: jg_agente              │
                                      │    │ ┌─────────────────────────────┐ ┌────────────────────┐ │
                                      │    │ │  jg_agente_conversacional   │ │  jg_agente_devops  │ │
                                      │    │ │  puerto :8001               │ │  puerto :8002      │ │
                                      │    │ └──────────────┬──────────────┘ └──────────┬─────────┘ │
                                      │    └────────────────┼───────────────────────────┼───────────┘
                                      │                     │                           │
                                      ▼                     ▼                           ▼
                        ┌──────────────────────────────┐ ┌──────────────────────┐ ┌─────────────────┐
                        │      jg_agente_postgres      │ │ Docker Socket Proxy  │ │ jg_hub (:8923)  │
                        │   Checkpoints & Auditoría    │ │  (Daemon Solo Lect.) │ │ Portal Público  │
                        │   (puerto 5433)              │ │  (:2375 interno)     │ │ Docs-as-Code    │
                        └──────────────────────────────┘ └──────────────────────┘ └─────────────────┘

4. Seguridad Perimetral y Zero-Trust

La plataforma incorpora defensas nativas contra los vectores de ataque más comunes en aplicaciones basadas en IA y ejecución de herramientas:

1. Defensa Anti-SSRF (Server-Side Request Forgery):
   • Resolución previa de DNS con rechazo de rangos privados (RFC 1918, RFC 3927 link-local, 127.0.0.0/8, IPv6 local).
   • Bloqueo de URLs de metadatos cloud de proveedores como AWS (169.254.169.254), GCP y Azure.
   • Implementado mediante backends de transporte seguro SSRFSafeSyncBackend y SSRFSafeAsyncBackend.
2. DNS Pinning en Capa de Socket:
   • Para impedir ataques Time-of-Check to Time-of-Use (TOCTOU) mediante DNS Rebinding, la conexión de socket se fija a la IP validada en el primer chequeo a nivel TCP.
3. Firmas Criptográficas HMAC-SHA256 con Anti-Replay:
   • Toda comunicación entre clientes externos (o Dashboard) y los Agentes viaja firmada criptográficamente con cabeceras canónicas obligatorias:
     • X-Signature: Firma hexadecimal en tiempo constante (hmac.compare_digest).
     • X-Timestamp: Epoch UNIX en segundos con ventana estricta de tolerancia $\le 300\text{ s}$.
     • X-Agent-ID: Identificador unívoco del agente destinatario.
     • X-Correlation-ID: Identificador de traza distribuida inyectado en cada línea de log.
4. Proxy Seguro de Docker Socket:
   • Los agentes con permisos de inspección DevOps se comunican con el daemon mediante un proxy restringido (docker-socket-proxy) en modo solo lectura (POST: 0, VOLUMES: 0, NETWORKS: 0), impidiendo la escalada de privilegios al host.
5. Sanitización contra Inyección de Comandos:
   • Doble patrón de expresiones regulares para diferenciar contextos de terminal (SHELL_INJECTION_PATTERN) de consultas con URLs y query strings (URL_SHELL_INJECTION_PATTERN).

5. Estructura de la Documentación

La arquitectura se detalla en los siguientes módulos especializados:

• Agente Cognitivo (Core): Runtime LangGraph (10 nodos), reducers de estado, checkpointing atómico DualPostgresSaver y catálogo de capacidades.
• Control Plane (Gobernanza HITL): Centro de mando, resolución atómica pesimista, reconciliación tolerante a fallos y protocolo HMAC.
• Control Plane (Operaciones y Resiliencia): Circuit Breakers, mapa de topología dinámico, widgets reactivos en tiempo real y comandos SRE.
• Ecosistema de Plugins: SDK oficial en PyPI, guía de desarrollo y catálogo de extensiones disponibles.

6. Política de Licenciamiento del Ecosistema

El ecosistema javiergalvez-ia equilibra la apertura comunitaria con la viabilidad empresarial mediante una estrategia homogénea: