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.