Skip to content

Portal system architecture

Reviewed October 28, 2026; client, lyric and publication follow-up November 3 for T-100498. This section describes repository snapshots, not a live inventory. Links next to claims point to exact files at reviewed commits; Source snapshots records the release lanes and limits of the review. A source merge, deployed Worker, installed app, and running process are separate facts.

Page Contents
Diagrams System map and request, identity, lyrics, comms, release, and failure flows
The central API Versioned contract, private origin, Tasks gateway, ticket live updates
Clients and publishers Web BFF, native app, iPad feeds, machine publishers, edge Workers
Portal origin server PHP/data ownership, background work, deployment and shared-data boundary
Lyrics and service systems Display pipeline, follower, capture, event spine, operational dependencies
Identity and trust boundaries OAuth, sessions, RBAC, HMAC, local controls, secret handling
Repositories and deployment Release lanes, rollback, failure triage, runbook links

Components and ownership

The staff data path is client → central API → PHP adapter → Portal database. portal-api publishes /api/v1/* and OAuth paths; the PHP Portal validates its opaque bearer tokens and reads current account status and RBAC. The Worker does not connect to the Portal SQL databases. Sources: 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.

The browser uses a PHP session and, for migrated features, a server-side BFF that holds API tokens. The universal iPhone/iPad app uses PortalCore for staff API calls. Service dashboards, the Assistant client, the local alert transport, and Q-SYS room controls/Utility have separate paths; “everything uses the API” would be incorrect. Sources: 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.

Lyrics use ProPresenter → PHP poller → shared cache → Ratchet WebSocket. Comms/panic ingest uses the central API, then RAM snapshots consumed by the lyric socket and private HTTP feeds. The lyric follower and service-timeline collector have separate local inputs and do not synchronously depend on the central API. Sources: 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.

Release lanes and important exceptions

Surface Reviewed configuration Source
Central API dev dev-api.ro.church → dev.portal.ro.church; Tasks service binding enabled only in dev portal-api · infra/environments/alpha/main.tf, portal-api · src/index.ts
Central API production api.ro.church → portal.ro.church; production apply gated by ENABLE_PRODUCTION_API=true portal-api · infra/environments/production/main.tf, portal-api · .gitlab-ci.yml
Portal dev deploys development; main deploys production portal · .gitlab-ci.yml, portal · .gitlab-ci.yml
iOS/iPadOS Debug and internal TestFlight use dev; Release configuration names production. Protected dev also has automatic Jamf rollout jobs portal-ios · Configuration/Debug.xcconfig, portal-ios · Configuration/TestFlight.xcconfig, portal-ios · Configuration/Release.xcconfig, portal-ios · .gitlab-ci.yml
Data Dev intentionally shares the production Technology budget ledger; dev is not a disposable data sandbox portal · docs/technology-budget-sql-ledger.md, portal · scripts/verify-environment-database-isolation.php
Worker state Portal business records remain at the origin; ticket-live uses Durable Object SQLite for its invalidation revision portal-api · src/ticket-live-hub.ts
Comms publisher Source found on the transcription feature branch; do not infer release/installation from its presence infrastructure/lyric-follower · macos/WorshipDataCaptureApp/Sources/WorshipDataCaptureApp/CommsPublisher.swift, infrastructure/lyric-follower · docs/deployment-pipeline.md

Reading deployment evidence

The reviewed production API source (e3a6ee2) has an older catalog than dev (4ede038). Resource availability must be checked against the matching branch catalog and deployed /api/v1/meta, not inferred from an app build or these docs. This review did not reproduce the October 25 live probes recorded in the earlier task comments. Sources: portal-api · src/contract.ts, portal-api · src/contract.ts, portal-api · src/index.ts.

The API's fixed VPC origin and nginx listeners are declared in source. The full public-hostname routing chain and deployed Access policies are not established by these files alone. See verification limits and failure triage. Sources: portal-api · infra/modules/portal-platform/main.tf, infra · nginx/hosts/rocc-db/sites-enabled/ro.church.conf.