Saltar a contenido

Diagramas: rutas y conexiones

Revisado flujos de origen, 28 de octubre de 2026. Las flechas sólidas son rutas de datos/solicitudes configuradas; las flechas discontinuas son rutas opcionales, solo para desarrollo o de respaldo. Estos diagramas no son un inventario de despliegue en vivo. Cada leyenda enlaza la evidencia de implementación.

1. Todo el sistema en una página

flowchart LR
  App["Cliente nativo del personal"] --> API["Worker de API central"]
  Browser["Navegador del personal"] --> PHP["Portal PHP / BFF"]
  PHP -->|"vistas migradas: bearer"| API
  Pub["Publicadores firmados"] --> API
  API -->|"servicio VPC fijo / túnel Goshen"| Nginx["nginx en rocc-db"]
  Nginx --> PHP
  PHP --> SQL[("Registros SQL del portal / RBAC")]
  API -.->|"vinculación de servicio de desarrollo"| Tasks["Worker de Tareas / autorización propia"]
  API --> Hub["Ticket-live DO / estado de revisión"]
  PP["ProPresenter"] --> Poll["Poller de letras PHP / caché"] --> WS["WebSocket de letras"]
  WS --> Dash["Dashboards / pantallas LAN"]

Fuentes: portal-api · src/index.ts, portal-api · infra/modules/portal-platform/main.tf, portal · dashboard/v2/api/lib/client.php, portal · dashboard/api/mobile/v1/lib/runtime.php, portal-api · src/ticket-live-hub.ts, portal · lyrics/poll_propresenter.php, portal · lyrics/server.php.

2. ¿Qué ruta toma cada cliente?

flowchart TB
  Staff["Funciones de API para el personal"] --> API["portal-api"]
  BFF["Vistas web migradas"] --> API
  Comms["Rama de publicador de Comms"] --> API
  Service["Modos de servicio de iPad"] --> LAN["Feeds locales de letras / planes / monitoreo"]
  Service -.->|"cargador de comms con sesión iniciada"| API
  Assistant["Pestaña Asistente"] --> Own["Asistente / Authentik"]
  Spare["Controles de sala del portal / Utilidad"] --> QRC["Host de Q-SYS administrado / QRC + HTTPS"]
  Timeline["Productores de línea de tiempo"] --> Collector["Recolector propio / SQL"]

Fuentes: portal-ios · Sources/PortalCore/APIClient.swift, portal-ios · Sources/PortalCore/AssistantClient.swift, portal-ios · RiverOaksServiceDashboard/ViewModel/DashboardViewModel.swift, portal-ios · Sources/QSysRoomUI/QSysNetwork.swift, portal-ios · Sources/QSysKit/QSysConfiguration.swift, portal-ios · RiverOaksUtility/App/RiverOaksUtilityApp.swift, infrastructure/service-timeline · src/service_timeline/client.py, infrastructure/lyric-follower · macos/WorshipDataCaptureApp/Sources/WorshipDataCaptureApp/CommsPublisher.swift.

3. Una solicitud de API, salto por salto

sequenceDiagram
  participant C as Cliente del personal
  participant W as Worker de API
  participant V as Servicio VPC fijo
  participant P as Adaptador Portal PHP
  participant D as Portal SQL
  C->>W: Recurso permitido + bearer
  W->>W: Comprobaciones de carril/ruta/método/tamaño/tasa
  W->>V: Solicitud saneada + ID de solicitud
  V->>P: Host del portal configurado y ruta del adaptador
  P->>D: Comprobaciones de token/cuenta/permiso actual
  D-->>P: Datos autorizados
  P-->>W: Respuesta del adaptador
  W-->>C: Respuesta saneada + IDs de solicitud/liberación

Esta secuencia es para recursos respaldados por PHP; las rutas directas de Worker y Tareas tienen manejadores separados. Fuentes: portal-api · src/index.ts, portal · dashboard/api/mobile/v1/lib/runtime.php.

4. Inicio de sesión (aplicación iOS)

sequenceDiagram
  participant A as Aplicación nativa
  participant W as Worker de API
  participant P as Portal / inicio de sesión de Google
  participant K as Llavero del dispositivo
  A->>W: Autorizar navegador, estado + desafío S256
  W-->>P: Redirigir a Portal auth/start.php correspondiente
  P-->>A: Código de devolución + estado
  A->>W: Intercambio de tokens + verificador
  W->>P: token.php
  P-->>A: Tokens de acceso + refresco rotatorios
  A->>K: Almacenamiento de tokens solo para dispositivos

Fuentes: portal-ios · RiverOaksPortal/App/WebAuthenticationService.swift, portal-ios · RiverOaksPortal/App/KeychainTokenVault.swift, portal-api · src/index.ts, portal · dashboard/api/mobile/v1/token.php.

5. Cómo usa el Portal web la API (BFF del lado del servidor)

sequenceDiagram
  participant B as Navegador
  participant P as Portal BFF / sesión PHP
  participant A as API canónica correspondiente
  B->>P: Solicitud de página autenticada por sesión
  P->>P: Conexión/callback, tokens OAuth en poder del servidor
  P->>A: Recurso permitido + bearer
  A-->>P: JSON autorizado
  P-->>B: Página renderizada / respuesta BFF

Fuente: portal · dashboard/v2/api/lib/client.php, portal · dashboard/v2/api/callback.php.

6. Actualizaciones en vivo de la cola de tickets

sequenceDiagram
  participant B as Navegador
  participant P as Portal BFF
  participant A as Worker de API
  participant H as TicketLiveHub
  B->>P: Solicitud de token en vivo protegida por CSRF
  P->>A: bearer en poder del servidor
  A->>P: Validar identidad/permiso del portal
  A-->>B: Token de conexión firmado de corta duración
  B->>A: Origen exacto / credenciales de subprotocolo WebSocket
  A->>H: Conectar después de la validación
  H-->>B: tickets.changed genéricos + revisión
  B->>P: Volver a obtener contenido autorizado, sondeo de respaldo

Fuentes: portal · dashboard/v2/tickets/api/live-token.php, portal-api · src/index.ts, portal-api · src/ticket-live.ts, portal-api · src/ticket-live-hub.ts, portal · docs/ticket-portal-live-updates.md.

7. Alertas: de una falla a un teléfono

flowchart LR
  Source["Q-SYS / Grafana / monitor"] --> Sign["Firma específica del publicador"]
  Sign --> API["Ingesta de alertas de API"] --> Policy["Política del publicador del portal / RBAC / preferencias"]
  Policy --> Inbox[("Registros de alertas del portal")]
  Inbox --> Foreground["Búsqueda / espera de alertas nativas"]
  Inbox --> Sender["Remitente APNs del portal"] --> Apple["Push de Apple"]
  Foreground -.-> LAN["Proxy de alertas LAN de desarrollo opcional"]

Fuentes: infra · nodered/instances/telegram/qsys-portal-alert.js, portal · dashboard/api/mobile/v1/lib/alert-ingest.php, portal · scripts/mobile-apns-worker.php, portal-ios · Sources/PortalCore/APIClient.swift.

8. Gateway de tareas (solo para desarrollo)

sequenceDiagram
  participant C as Cliente nativo
  participant A as API de desarrollo
  participant P as Bootstrap del portal de desarrollo
  participant T as Vinculación del servicio de Tareas
  C->>A: bearer del portal / ruta de tarea explícita
  A->>P: Identidad activa actual del personal
  P-->>A: Identidad validada
  A->>T: Afirmación de corta duración vinculada a la solicitud
  T->>T: Autorización de tareas / versión de tarea
  T-->>C: Resultado de tarea validado a través de la API

Fuentes: portal-api · src/index.ts, portal-api · docs/TASKS.md, portal-api · infra/modules/portal-platform/main.tf.

9. Ruta de letras en vivo (no detrás de la API)

flowchart LR
  PP["ProPresenter"] --> Poll["Poller PHP"] --> Cache[("Caché RAM compartida")]
  Cache --> WS["Ratchet :8081"] --> Display["Pantallas / iPads"]
  WS --> Follower["Observador de sombra de loopback :8094"]
  PP --> Follower
  QRC["Q-SYS LTC"] --> Follower
  Follower --> Proposal["Evidencia / propuesta; disparador en vivo deshabilitado"]
  WS --> Proxy["Nginx privado /ws"] --> Browser["Navegador LAN"]

Fuentes: portal · lyrics/poll_propresenter.php, portal · lyrics/server.php, infrastructure/lyric-follower · systemd/ro-lyric-shadow.service, infrastructure/lyric-follower · src/lyric_follower/pp_agent.py, infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf.

10. Comms y feed de pánico a través de la API

flowchart LR
  Mac["Publicador de rama de características de transcripción"] -->|"instantánea HMAC"| API["API de desarrollo"]
  API --> PHP["Verificación del portal / ordenamiento"] --> RAM[("Instantáneas RAM de carril")]
  RAM --> WS["Marcos WebSocket de comms opcionales"] --> Pad["Panel de iPad"]
  RAM --> HTTP["Alias JSON de nginx privado"] -.->|"respaldo REST"| Pad
  PHP -.->|"GET comms con sesión iniciada"| Pad

Fuentes: infrastructure/lyric-follower · macos/WorshipDataCaptureApp/Sources/WorshipDataCaptureApp/CommsPublisher.swift, portal · dashboard/api/mobile/v1/lib/comms.php, portal · lyrics/comms_feed.php, portal-ios · RiverOaksServiceDashboard/Models/DashboardModels.swift, infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf. La opción no es autorización; consulte límite de privacidad.

11. Pipeline de diapositivas de sermones

flowchart LR
  Upload["Carga del portal"] --> Drive["Drive / caché privado"]
  Upload --> Outbox[("Registros de versión / bandeja de salida")]
  Outbox --> Extract["Worker de extracción"] --> Deliver["Worker de presentación"]
  Drive --> Extract
  Deliver --> Receiver["Receptor / importación de Mac restringido"]
  Drive --> Original["Destino de Worship Keynote"]
  Receiver --> Notify["Notificación / telemetría"]

Fuentes: portal · dashboard/v2/sermon-slides/process-upload.php, portal · scripts/sermon-slide-extraction-worker.py, portal · scripts/sermon-slide-propresenter-worker.py, portal · scripts/sermon-propresenter-receive.py, portal · scripts/sermon-worship-receive.sh.

12. A dónde va cada nombre de host público

flowchart LR
  APIHost["api.ro.church / dev-api.ro.church"] --> API["Worker canónico del personal"]
  API -->|"VPC fijo"| Origin["Vhost de nginx del portal correspondiente"]
  PublicWeb["Nombres de host del portal / letras públicos"] -.->|"la cadena de enrutamiento externa necesita verificación"| Origin
  Forms["Entrada de formularios"] --> FW["Worker de formularios / D1 / R2 / Cola"]
  Links["Entrada de enlaces cortos"] --> LW["Worker de enlaces cortos / D1"]
  Congregation["Aplicación de la congregación"] --> CW["Worker separado de contenido/alertas"]
  Docs["docs.ro.church"] --> Pages["Páginas / Límite de acceso"]

Fuentes: portal-api · infra/environments/alpha/main.tf, portal-api · infra/environments/production/main.tf, infra · nginx/hosts/rocc-db/sites-enabled/ro.church.conf, cloudflare-forms · src/index.ts, cloudflare-short-links · src/index.ts, church-app · services/alerts-api/src/worker.ts, docs · README.md. Las rutas de host externas no se demuestran únicamente con estas definiciones de origen/Worker.

13. Nombres solo para LAN

flowchart LR
  LAN["Cliente LAN / VPN"] --> ACL["ACL de origen de nginx privado"]
  ACL --> Lyrics["Rutas /ws y feed de lyrics.riveroaks.cc"]
  ACL --> Songs["songs.riveroaks.cc"] --> Auth["Authentik"]
  ACL --> Control["Rutas del navegador de control de letras"] --> Auth
  ACL --> IPad["Excepciones POST de control de iPad exactas"]
  Capture["Cliente de captura autenticado por bearer"] --> Special["Ruta de programación de captura separada"]

Fuentes: infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf, infra · nginx/hosts/rocc-db/sites-enabled/songs.riveroaks.cc.conf, infrastructure/lyric-follower · server/planning_center_api.py. La programación de captura difiere explícitamente del acceso anónimo a LAN/dashboard.

14. Orden de lanzamiento entre repositorios

flowchart LR
  Origin["1. Adaptador de desarrollo del portal + esquema"] --> Edge["2. Contrato de desarrollo de API + humo"]
  Edge --> App["3. Desarrollo de iOS / aceptación de dispositivo controlado"]
  App --> Accept["4. Aceptación con datos seguros"]
  Accept -.->|"promoción web/API aprobada"| P["5. Portal principal"]
  P -.-> A["6. API principal / puerta de producción"]
  Accept -.-> Native["El lanzamiento de producción nativo es separado"]

Este es el orden de compatibilidad recomendado. Fuentes: portal · .gitlab-ci.yml, portal-api · .gitlab-ci.yml, portal-ios · .gitlab-ci.yml, portal-api · docs/MIGRATION.md.

15. Qué se rompe si X está caído

flowchart TB
  Edge["API / VPC no disponible"] --> Staff["Datos de API y BFF del personal no disponibles"]
  Edge --> Comms["Nueva publicación de comms no disponible"]
  Origin["rocc-db no disponible"] --> Shared["Falla el origen del portal + servicios compartidos de letras/control"]
  PP["ProPresenter no disponible"] --> Fresh["Nuevas observaciones de letras/cuenta regresiva no disponibles"]
  Collector["Recolector de línea de tiempo no disponible"] --> Spool["Almacenamiento local dentro de la capacidad configurada"]
  APNs["Apple push no disponible"] --> Background["Notificaciones en segundo plano retrasadas / ausentes"]

El impacto de la falla se infiere del gráfico de origen, no de una prueba de interrupción. Fuentes: portal-api · src/index.ts, portal · lyrics/poll_propresenter.php, infrastructure/lyric-follower · systemd/ro-lyric-shadow.service, infrastructure/service-timeline · src/service_timeline/spool.py, portal · scripts/mobile-apns-worker.php. Consulte runbooks y primeras comprobaciones.