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.