Arquitectura del sistema del portal
Revisado el 28 de octubre de 2026; seguimiento de clientes, letras y publicaciones el 3 de noviembre para T-100498. Esta sección describe instantáneas de repositorios, no un inventario en vivo. Los enlaces junto a las afirmaciones apuntan a archivos exactos en commits revisados; Instantáneas de origen registra los carriles de lanzamiento y los límites de la revisión. Una fusión de origen, un Worker desplegado, una aplicación instalada y un proceso en ejecución son hechos separados.
| Página | Contenidos |
|---|---|
| Diagramas | Mapa del sistema y flujos de solicitudes, identidad, letras, comunicaciones, lanzamientos y fallos |
| La API central | Contrato versionado, origen privado, puerta de enlace de Tareas, actualizaciones en vivo de tickets |
| Clientes y publicadores | Web BFF, aplicación nativa, feeds de iPad, publicadores de máquinas, Workers de borde |
| Servidor de origen del portal | Propiedad de PHP/datos, trabajo en segundo plano, límite de despliegue y datos compartidos |
| Letras y sistemas de servicio | Canal de visualización, seguidor, captura, columna vertebral de eventos, dependencias operativas |
| Identidad y límites de confianza | OAuth, sesiones, RBAC, HMAC, controles locales, manejo de secretos |
| Repositorios y despliegue | Carriles de lanzamiento, reversión, triaje de fallos, enlaces a runbooks |
Componentes y propiedad
La ruta de datos del personal es cliente → API central → adaptador PHP → base de datos del Portal.
portal-api publica las rutas /api/v1/* y OAuth; el Portal PHP valida sus
tokens portadores opacos y lee el estado actual de la cuenta y RBAC. El Worker no se conecta a las bases de datos SQL del Portal. Fuentes:
portal-api · src/contract.ts, portal-api · src/index.ts,
portal · dashboard/api/mobile/v1/lib/runtime.php,
portal · dashboard/api/mobile/v1/lib/tokens.php.
El navegador utiliza una sesión PHP y, para las funciones migradas, un BFF del lado del servidor
que contiene tokens de API. La aplicación universal para iPhone/iPad utiliza PortalCore para las llamadas a la API del personal. Los paneles de servicio, el cliente Asistente, el transporte de alertas local y los controles de sala Q-SYS/Utilidad tienen rutas separadas; sería incorrecto decir "todo usa la API". Fuentes:
portal · dashboard/v2/api/lib/client.php,
portal-ios · Sources/PortalCore/APIClient.swift,
portal-ios · Sources/PortalCore/AssistantClient.swift,
portal-ios · RiverOaksServiceDashboard/Models/DashboardConfiguration.swift,
portal-ios · Sources/QSysRoomUI/QSysNetwork.swift.
Las letras usan ProPresenter → poller PHP → caché compartida → Ratchet WebSocket.
La ingesta de comunicaciones/pánico utiliza la API central, luego instantáneas de RAM consumidas por el socket de letras y feeds HTTP privados. El seguidor de letras y el colector de la línea de tiempo del servicio tienen entradas locales separadas y no dependen sincrónicamente de la API central. Fuentes:
portal · lyrics/poll_propresenter.php, portal · lyrics/server.php,
portal · lyrics/comms_feed.php,
portal · dashboard/api/mobile/v1/lib/comms.php,
infrastructure/lyric-follower · systemd/ro-lyric-shadow.service,
infrastructure/service-timeline · src/service_timeline/collector.py.
Carriles de lanzamiento y excepciones importantes
| Superficie | Configuración revisada | Origen |
|---|---|---|
| API central de desarrollo | dev-api.ro.church → dev.portal.ro.church; enlace del servicio de Tareas habilitado solo en desarrollo |
portal-api · infra/environments/alpha/main.tf, portal-api · src/index.ts |
| API central de producción | api.ro.church → portal.ro.church; aplicación de producción controlada por ENABLE_PRODUCTION_API=true |
portal-api · infra/environments/production/main.tf, portal-api · .gitlab-ci.yml |
| Portal | dev despliega desarrollo; main despliega producción |
portal · .gitlab-ci.yml, portal · .gitlab-ci.yml |
| iOS/iPadOS | Las versiones de depuración y TestFlight internas usan desarrollo; la configuración de Lanzamiento nombra la producción. El dev protegido también tiene trabajos automáticos de implementación de Jamf |
portal-ios · Configuration/Debug.xcconfig, portal-ios · Configuration/TestFlight.xcconfig, portal-ios · Configuration/Release.xcconfig, portal-ios · .gitlab-ci.yml |
| Datos | El desarrollo comparte intencionalmente el libro mayor de presupuesto tecnológico de producción; el desarrollo no es un sandbox de datos desechable | portal · docs/technology-budget-sql-ledger.md, portal · scripts/verify-environment-database-isolation.php |
| Estado del Worker | Los registros comerciales del portal permanecen en el origen; ticket-live utiliza Durable Object SQLite para su revisión de invalidación | portal-api · src/ticket-live-hub.ts |
| Publicador de comunicaciones | Origen encontrado en la rama de características de transcripción; no inferir lanzamiento/instalación de su presencia | infrastructure/lyric-follower · macos/WorshipDataCaptureApp/Sources/WorshipDataCaptureApp/CommsPublisher.swift, infrastructure/lyric-follower · docs/deployment-pipeline.md |
Lectura de evidencia de despliegue
El código fuente de la API de producción revisado (e3a6ee2) tiene un catálogo más antiguo que el de desarrollo
(4ede038). La disponibilidad de recursos debe verificarse contra el catálogo de la rama coincidente
y el /api/v1/meta desplegado, no inferirse de una compilación de aplicación o de estos documentos. Esta revisión no reprodujo las sondas en vivo del 25 de octubre registradas
en los comentarios de tareas anteriores. Fuentes:
portal-api · src/contract.ts, portal-api · src/contract.ts,
portal-api · src/index.ts.
El origen fijo de VPC de la API y los oyentes de nginx se declaran en el código fuente. La cadena de enrutamiento completa del nombre de host público y las políticas de acceso desplegadas no se establecen solo con estos archivos. Consulte límites de verificación
y triaje de fallos.
Fuentes: portal-api · infra/modules/portal-platform/main.tf,
infra · nginx/hosts/rocc-db/sites-enabled/ro.church.conf.