Skip to content

Clients and publishers

1. iOS app (riveroaks/portal-ios)

The universal SwiftUI app shares API requests, models and PKCE through the local PortalCore package. The app's AppEnvironment validates the API/web hostname pair; APIConfiguration builds endpoint URLs. Sources: portal-ios · Sources/PortalCore/APIClient.swift, portal-ios · Sources/PortalCore/PKCE.swift, portal-ios · Sources/PortalCore/APIConfiguration.swift, portal-ios · RiverOaksPortal/App/AppEnvironment.swift.

Build configuration API / browser origin Source
Debug dev-api.ro.church / dev.portal.ro.church portal-ios · Configuration/Debug.xcconfig
Internal TestFlight Same dev pair; APNs production entitlement portal-ios · Configuration/TestFlight.xcconfig
Release api.ro.church / portal.ro.church portal-ios · Configuration/Release.xcconfig

Configuration is not proof that a production App Store build shipped. Current protected-dev CI automatically uploads internal TestFlight builds and has a separate Jamf Portal-iPad rollout job; the standalone dashboard release is manual. Source: portal-ios · .gitlab-ci.yml.

Sign-in uses ASWebAuthenticationSession and PKCE. The app keeps Portal tokens in a device-only Keychain item. Server checks remain authoritative; client permissions control presentation. Sources: portal-ios · RiverOaksPortal/App/WebAuthenticationService.swift, portal-ios · RiverOaksPortal/App/KeychainTokenVault.swift, portal-ios · CONTRIBUTING.md.

The Assistant tab has its own Authentik/PKCE client. It does not call the reserved Portal /api/v1/assistant implementation. Sources: portal-ios · Sources/PortalCore/AssistantClient.swift, portal-api · src/contract.ts.

2. iPad surfaces

Surface Central API relationship Evidence
Universal Portal app, Staff Portal mode Staff features use the API; service modes embed LAN dashboards portal-ios · RiverOaksPortal/Views/ServiceModes/IPadPortalView.swift
Standalone Service Dashboard Own target, LAN feeds; no staff token requirement for those feeds portal-ios · project.yml, portal-ios · RiverOaksServiceDashboard/Models/DashboardConfiguration.swift
Standalone River Oaks Utility Q-SYS room controls through shared QSysKit/QSysRoomUI; no Portal API or staff sign-in portal-ios · RiverOaksUtility/App/RiverOaksUtilityApp.swift, portal-ios · Sources/QSysKit/QSysConfiguration.swift
Browser lyrics/confidence pages Display WebSocket independent of the staff API portal · lyrics/index.html, portal · lyrics/confidence.html

The dashboard's managed configuration supplies/overrides feed URLs; defaults are in portal-ios · RiverOaksServiceDashboard/Models/DashboardConfiguration.swift. The table maps each default feed to its server-side boundary.

Panel Path Server/source
Acoustics/timecode Service Monitor HTTP/SSE on 10.200.21.38:8080 service-monitor · app/backend/internal/handlers/handlers.go, portal-ios · docs/IPAD_SERVICE_DASHBOARD.md
Lyrics, stage notes, pushed countdowns Lyrics WebSocket, default ws://10.200.24.42:8081/ portal · lyrics/server.php, portal · lyrics/poll_propresenter.php
Plans, elements, keys, notes lyrics.riveroaks.cc/songs/api.php portal · lyrics/songs/api.php, portal · lyrics/songs/service_elements.php
Comms/panic Opt-in lyric frames plus private /comms/state.json and /comms/panic.json; signed-in host can supply API comms loader portal · lyrics/comms_feed.php, portal-ios · RiverOaksServiceDashboard/ViewModel/DashboardViewModel.swift, infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf
Countdown fallback Narrow ProPresenter proxy routes portal-ios · RiverOaksServiceDashboard/ViewModel/DashboardViewModel.swift, infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf
Follower mode/recording lyrics-control.riveroaks.cc/api/ipad/*, source-allowlisted POST routes infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf

Comms REST polling uses a 15-second safety interval while pushes are fresh and returns to one second when disconnected or silent for 20 seconds. The model rejects older snapshots/revisions. Final transcript lines may remain visible for a minute; a stale lane is not necessarily a blank panel. Sources: portal-ios · RiverOaksServiceDashboard/Models/DashboardModels.swift, portal-ios · RiverOaksServiceDashboard/ViewModel/DashboardViewModel.swift.

Q-SYS room controls: the Portal and Utility apps now share QSysKit and QSysRoomUI. Room controls use direct LAN QRC (default TCP 1710) and HTTPS assets, independently of the central API. Jamf qsys.host can select a valid host; certificate trust uses managed SPKI pins or per-host first-use trust. Downloaded assets cannot redirect QRC. Portal's admin mode exposes room controls; staff and qsys restrict the visible surfaces. Utility requires a valid managed host and shows a waiting screen instead of guessing a core. These are source capabilities, not proof of deployment to a production room. Sources: portal-ios · Sources/QSysKit/QSysConfiguration.swift, portal-ios · Sources/QSysRoomUI/QSysNetwork.swift, portal-ios · RiverOaksUtility/App/RiverOaksUtilityApp.swift, portal-ios · docs/QSYS_ROOM_CONTROLS.md.

Utility is an iPad-only Ad Hoc/Jamf target with a manual protected-dev release job. TestFlight and the universal Portal-iPad Jamf lane remain automatic on protected dev; a Utility profile-expiry schedule only checks expiry and cannot release an app. Sources: portal-ios · .gitlab-ci.yml, portal-ios · docs/UTILITY.md.

LAN service alerts

The audio dashboard also polls the private /comms/alerts.json snapshot every two seconds, without a staff token. This is a separate path from authenticated central-API alert lists, preferences and APNs registration. The Portal writes a bounded RAM-backed snapshot after alert commits: only service/technology categories and sermon/operational-alert resource types, at most ten entries within a fifteen-minute window. A failed feed read keeps the previous entries; client freshness rules age them out. Sources: portal-ios · RiverOaksServiceDashboard/ViewModel/PanicAlertMonitor.swift, portal-ios · RiverOaksServiceDashboard/Models/DashboardConfiguration.swift, portal-ios · RiverOaksServiceDashboard/Models/DashboardModels.swift, portal · dashboard/api/mobile/v1/lib/alerts.php.

The nginx alias is on the existing LAN/source-restricted lyric vhost; it is not an anonymous internet API. Source: infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf.

3. Web Portal (riveroaks/portal)

The browser keeps its Portal session cookie. Migrated pages call a PHP BFF; that server holds the OAuth tokens and calls the matching canonical API. The connect/callback pair checks state and PKCE, and logout revokes the family. Sources: portal · dashboard/v2/api/lib/client.php, portal · dashboard/v2/api/connect.php, portal · dashboard/v2/api/callback.php, portal · docs/WEB_CANONICAL_API_MIGRATION.md.

Coverage is incremental: use the migration checklist to distinguish API-backed views from remaining PHP services and mutations. Production BFF enablement requires explicit matching runtime configuration; the canonical dev host has defaults. Sources: portal · docs/WEB_CANONICAL_API_MIGRATION.md, portal · dashboard/v2/api/lib/client.php, portal · dashboard/api/mobile/v1/lib/core.php.

For web-only destinations the native app requests a one-use handoff through web-session; the server returns an allowlisted destination with a fragment secret, and web-continue.php consumes it into a family-bound PHP session. Sources: portal-ios · Sources/PortalCore/APIClient.swift, portal · dashboard/api/mobile/v1/web-session.php, portal · dashboard/api/mobile/v1/web-continue.php.

4. Machine publishers (push into the API)

Producer API connection and authorization Source
Q-SYS / Node-RED Node-RED signs alert-ingest requests with publisher-scoped HMAC infra · nodered/instances/telegram/qsys-portal-alert.js, portal · dashboard/api/mobile/v1/lib/alert-ingest.php
Grafana adapter Verifies Grafana's signature and re-signs into Portal alert format infra · docs/alerting/grafana-portal-adapter.md
Service Monitor Configurable signed alert publisher; configure only an API lane whose catalog supports ingest service-monitor · deploy/ota/service-monitor-alert, portal-api · src/contract.ts, portal-api · src/contract.ts
Worship Data Capture transcription branch Comms/panic snapshots signed with lane key; bounded latest state, no outage upload backlog infrastructure/lyric-follower · macos/WorshipDataCaptureApp/Sources/WorshipDataCaptureApp/CommsPublisher.swift, infrastructure/lyric-follower · macos/WorshipDataCaptureApp/Sources/WorshipDataCaptureCore/Transcription.swift
Portal integration helpers Ticket-email/task-alert resources use service auth rather than a user session portal-api · src/contract.ts, portal · dashboard/api/mobile/v1/ticket-email-reply.php, portal · dashboard/api/mobile/v1/task-alert-ingest.php

Alert publishers cannot supply arbitrary recipients: the Portal validates the publisher policy, permissions and user preferences. Comms/panic use a different signature contract. See identity. Source: portal · dashboard/api/mobile/v1/lib/alert-ingest.php.

5. Edge Workers around the Portal

These have their own data/storage and release gates; they do not become part of portal-api because they run on Cloudflare.

Repository Flow and central API relationship Evidence
cloudflare-forms Turnstile → encrypted submission/attachments → D1, R2 and Queue → application adapter; queue retries/DLQ. Delivery uses a signed configured adapter URL rather than the staff bearer contract cloudflare-forms · src/index.ts, cloudflare-forms · src/adapter.ts, cloudflare-forms · src/crypto.ts
cloudflare-email HMAC/idempotent caller → queue or defined synchronous attachment path → Cloudflare Email Service; D1 tracks delivery/quota metadata cloudflare-email · src/index.ts, cloudflare-email · README.md
cloudflare-short-links Public redirect → D1; separate Access/HMAC-protected admin namespace used by Portal cloudflare-short-links · src/index.ts, cloudflare-short-links · src/admin.ts
church-app alerts API Congregation content/alerts Worker, separate contract and D1; not the staff API church-app · services/alerts-api/src/worker.ts
cloudflare-mobile-edge Earlier optional gateway; source defaults custom domains off and manual activation. Do not infer live routing from that design cloudflare-mobile-edge · README.md, cloudflare-mobile-edge · infra/modules/mobile-edge/main.tf