Contenedores (C4 nivel 2)¶

Responde: ¿qué procesos y almacenes hay, dónde corre cada uno y cómo se hablan?

Cada flecha indica su protocolo y, cuando existe, su mecanismo de autenticación.

flowchart TB
  B["🌐 Navegador"]

  subgraph vercel["Vercel"]
    FE["<b>Frontend + BFF</b><br/>Next.js 16 · React 19<br/><i>35 páginas · 62 rutas BFF</i>"]
  end

  subgraph nube["Nube"]
    API["<b>Cloud API</b><br/>Go 1.24 · Gin<br/><i>Cloud Run</i>"]
    PG[("<b>Postgres</b><br/>identidad, RBAC,<br/>dispositivos, claves,<br/>layouts, logs")]
    MG[("<b>MongoDB</b><br/>mediciones")]
    RD[("<b>Redis</b><br/>rate limit<br/>idempotencia")]
    SB["<b>Supabase</b><br/>Auth · JWKS · correo"]
  end

  subgraph pi["Raspberry Pi — planta"]
    HI["<b>Historian</b><br/>Python · Modbus"]
    IF[("<b>InfluxDB</b><br/>historian_semantic")]
    FA["<b>FA³ST</b><br/>servidor AAS<br/><i>override opcional</i>"]
    ED["<b>Edge Pi Service</b><br/>Go · Gin"]
    SQ[("<b>SQLite</b><br/>outbox + watermark")]
  end

  PLC["⚙️ PLC"]

  B -->|"HTTPS · cookie de sesión"| FE
  B -->|"HTTPS · login"| SB
  FE -->|"HTTP(S) · Bearer JWT + X-Tenant-ID"| API

  API -->|"pgx · DATABASE_URL"| PG
  API -->|"driver v2 · MONGO_URI"| MG
  API -->|"go-redis · REDIS_URL"| RD
  API -->|"HTTPS · JWKS + Admin API"| SB
  API -->|"HTTP(S) · GET /status /health /telemetry<br/><b>sin autenticación</b>"| ED

  ED -->|"HTTP(S) · X-Api-Key<br/>+ Idempotency-Key"| API
  ED -->|"HTTP · Flux + INFLUX_TOKEN"| IF
  ED -->|"archivo local"| SQ

  HI -->|"Modbus TCP · solo lectura"| PLC
  HI -->|"HTTP · escritura + INFLUX_TOKEN"| IF
  HI -.->|"archivo XML compartido"| FA

  classDef app fill:#1168bd,stroke:#0b4884,color:#fff
  classDef store fill:#438dd5,stroke:#2e6295,color:#fff
  classDef ext fill:#999,stroke:#6b6b6b,color:#fff
  classDef opt fill:#1168bd,stroke:#0b4884,color:#fff,stroke-dasharray: 5 5
  class FE,API,ED,HI app
  class FA opt
  class PG,MG,RD,IF,SQ store
  class PLC,SB,B ext

Contenedores¶

En la nube¶

En la Raspberry Pi¶

Las dos superficies de la Cloud API¶

Es la decisión estructural más importante del backend: dos superficies HTTP con cadenas de middleware completamente distintas.

Los paths exactos, los nombres de header, el orden de la cadena de middlewares y el esquema de respuesta pertenecen al repositorio del Cloud y no se replican acá. Son el contrato, y su fuente de verdad es:

• docs/openapi.yaml — especificación de ambas superficies
• internal/api/middleware/middleware.go — cadena de ABM
• internal/consumers/middleware/ — cadena de ingesta
• internal/routes/url_mappings.go — registro de rutas

La explicación de la semántica de cada frontera está en integraciones.

Componentes internos del Edge¶

El Edge es el contenedor con la lógica más delicada —evitar que se pierdan o dupliquen datos ante cortes de enlace—.

Capacidad del outbox¶

Una decisión del Edge plantea como contexto un buffer offline de 24 h o más. La implementación no lo garantiza. Lo que el código impone es un límite de filas, OUTBOX_MAX_ROWS, con valor por defecto 100000, que el bundle no modifica: la guía de despliegue en la Pi estima que eso equivale a unas 1,5 h de backlog a ~18 eventos/s.

Al llenarse el outbox, el Edge deja de aceptar eventos nuevos pero no pierde datos: el watermark solo avanza sobre los eventos efectivamente aceptados, así que el mecanismo es de contrapresión, no de descarte.

Alcanzar 24 h reales requiere subir OUTBOX_MAX_ROWS y validar el espacio en disco de la Pi.

Degradación¶

Qué deja de funcionar cuando cae cada pieza:

Dos huecos del dibujo¶

Los chequeos del Cloud hacia la Pi van sin credenciales. El Edge admite un secreto de cabecera opcional y el Cloud no lo envía, así que el contrato inbound apoya en una red privada que no está configurada en ningún repositorio. El modelo completo y el riesgo asumido están en seguridad.

El heartbeat no existe en ninguno de los dos extremos. El Cloud responde 501 y el paquete correspondiente del Edge está vacío, así que el estado de un dispositivo se obtiene solo por los chequeos que inicia el Cloud: una Pi que deja de enviar no avisa.

Tres cosas del despliegue no están en ningún repositorio y hay que mirarlas en las consolas: la topología de red entre el Cloud y la planta, el proveedor de MongoDB en producción, y quién recolecta las métricas Prometheus que exponen el Cloud y el Edge.

Siguiente nivel¶

El detalle de cada frontera —semántica, errores, secuencias— está en integraciones, y el recorrido completo de una variable en flujo de datos.