Inicio / Documentación / docs/ARCHITECTURE.md

🏗️ Arquitectura del Social Bot Scheduler#

El Social Bot Scheduler ha evolucionado hacia una infraestructura de Matriz Tecnológica. No es un solo producto, sino un ecosistema modular donde puedes intercambiar piezas de software según tus necesidades.

📐 Los 3 Ejes Fundamentales#

1. 📤 Eje de Origen (Emisores)#

Es el componente que posee la lógica de programación. Revisa el archivo posts.json, valida las fechas y "dispara" el evento hacia el puente.

• Implementaciones: Python (Pydantic), Go (Native), Node.js (Axios), Laravel (Artisan), Rust (reqwest), C# (.NET HttpClient), Java (Spring Boot), Elixir, Zig, Swift, Next.js 15, Apollo (GraphQL), Rust (MQTT), Go (gRPC), Node + Kafka.

2. 🌉 Eje del Puente (n8n + Guardrails)#

Es la capa de abstracción y resiliencia. Recibe un Webhook genérico y asegura que la entrega a redes sociales sea segura.

• Ventaja: El emisor no necesita conocer las APIs de las redes sociales.
• Guardrails: Implementa Idempotencia (evita duplicados), Circuit Breakers (protección contra caídas) y DLQ (cola de errores).

3. 📥 Eje de Destino (Receptores + Dashboards)#

Es la capa de auditoría y visualización. n8n envía una copia del post finalizado a estos servicios.

• Implementaciones: PHP, Go, Node.js, FastAPI, React, Symfony, Ruby, Flask, Kotlin (Ktor), Erlang (Cowboy), FastAPI + RAG, Go consumer, Supabase (PostgREST), Python (gRPC), Hasura, Crystal (Kemal), Dart (Shelf).
• Persistencia: Cada destino orquesta su propio motor de base de datos (MySQL, PostgreSQL, MongoDB, Cassandra, etc.).

🧩 Matriz de Casos Implementados#

Nota

Caso 19 (F# → Clojure/Ring, XTDB, puerto 8099) es el único caso pendiente (diferido). Los 19 casos restantes (01–18 y 20) están implementados y operativos.

🔄 Diagrama de Flujo Universal#

graph LR
    subgraph "ORIGIN (Emisor)"
        A[JSON Config] --> B{Scheduler}
        B -- POST --> C((n8n Webhook))
    end

    subgraph "BRIDGE (n8n + Guardrails)"
        C((n8n Webhook)) --> CM{Idempotency Check}
        CM -- New --> D[Workflow Logic]
        CM -- Duplicate --> C1[Discard / 200 OK]
        D --> CB{Circuit Breaker}
        CB -- Closed --> E[Social API 1]
        CB -- Closed --> F[Social API 2]
        CB -- Open --> DLQ[Dead Letter Queue]
        E & F -- Error --> DLQ
        D -- Mirror POST --> G((Dest API))
    end

    subgraph "DESTINATION (Visualizer & Multi-DB)"
        G --> H1[MySQL/MariaDB/PSQL]
        G --> H2[Mongo/Cassandra]
        G --> H3[Redis/SQLite/MSSQL]
        H1 & H2 & H3 -- Serve --> I[Web Dashboard]
    end

🧬 Catálogo de Patrones Arquitectónicos#

Consejo

Estos patrones son los pilares que permiten que el sistema sea escalable y políglota.

1. 🏗️ Microservices Architecture#

El sistema se descompone en servicios independientes, cada uno en su propio contenedor Docker.

• Evidencia: docker-compose.yml define ~46 servicios (perfil full: 19 casos con receptor + BD, más núcleo n8n y observabilidad).
• Beneficio: Aislamiento total. Un fallo en el Caso 02 no afecta al resto.

2. ⚡ Event-Driven / Webhooks#

Comunicación basada en eventos HTTP asíncronos.

• Evidencia: Emisores en cases/*/origin/ disparan hacia URLs de n8n.
• Beneficio: Desacoplamiento total entre emisor y receptor.

3. 🕸️ Mediator / Hub-and-Spoke#

n8n actúa como el mediador central (Hub) donde convergen todos los flujos.

• Por qué importa: Centraliza la lógica de transformación y permite añadir casos sin tocar código existente.

4. 🛡️ Resilience Patterns (Circuit Breaker & Idempotency)#

El sistema protege activamente la integridad de los datos y la salud de los proveedores externos.

• Idempotencia: scripts/check_idempotency.py evita duplicados.
• Disyuntor: scripts/circuit_breaker.py previene saturación ante fallos externos.

📊 Observabilidad CNCF#

El stack implementa el estándar industrial de monitoreo:

graph LR
    A[n8n] -- /metrics --> B(Prometheus)
    C[Contenedores] -- cAdvisor --> B
    B -- PromQL --> D[Grafana Dashboard]
    E[Admin] -- HTTP :3000 --> D

Importante

Prometheus realiza "scraping" cada 15 segundos para mantener datos frescos sin saturar el runtime.

🚀 Despliegue y Escalabilidad#

El despliegue soporta múltiples entornos:

• Local (Secure-default): make up-secure.
• Kubernetes: Manifiestos en k8s/base/ listos para Kustomize.
• Edge Deployment: Perfil make up-edge con proxy Caddy.

📋 Tabla Resumen de Patrones#

Arquitectura diseñada para la resiliencia por Vladimir Acuña