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.
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)
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 |