Diagrams: paths and connections
Reviewed source flows, October 28, 2026. Solid arrows are configured data/request paths; dashed arrows are optional, dev-only or fallback paths. These diagrams are not a live deployment inventory. Each caption links implementation evidence.
1. The whole system on one page
flowchart LR
App["Native staff client"] --> API["Central API Worker"]
Browser["Staff browser"] --> PHP["Portal PHP / BFF"]
PHP -->|"migrated views: bearer"| API
Pub["Signed publishers"] --> API
API -->|"fixed VPC service / Goshen tunnel"| Nginx["nginx on rocc-db"]
Nginx --> PHP
PHP --> SQL[("Portal SQL records / RBAC")]
API -.->|"dev service binding"| Tasks["Tasks Worker / own authorization"]
API --> Hub["Ticket-live DO / revision state"]
PP["ProPresenter"] --> Poll["PHP lyric poller / cache"] --> WS["Lyrics WebSocket"]
WS --> Dash["LAN dashboards / displays"]
Sources: portal-api · src/index.ts, portal-api · infra/modules/portal-platform/main.tf,
portal · dashboard/v2/api/lib/client.php,
portal · dashboard/api/mobile/v1/lib/runtime.php,
portal-api · src/ticket-live-hub.ts, portal · lyrics/poll_propresenter.php,
portal · lyrics/server.php.
2. Which path does each client take?
flowchart TB
Staff["Staff API features"] --> API["portal-api"]
BFF["Migrated web views"] --> API
Comms["Comms publisher branch"] --> API
Service["iPad service modes"] --> LAN["Local lyric / plan / monitor feeds"]
Service -.->|"signed-in comms loader"| API
Assistant["Assistant tab"] --> Own["Assistant / Authentik"]
Spare["Portal room controls / Utility"] --> QRC["Managed Q-SYS host / QRC + HTTPS"]
Timeline["Timeline producers"] --> Collector["Own collector / SQL"]
Sources: portal-ios · Sources/PortalCore/APIClient.swift,
portal-ios · Sources/PortalCore/AssistantClient.swift,
portal-ios · RiverOaksServiceDashboard/ViewModel/DashboardViewModel.swift,
portal-ios · Sources/QSysRoomUI/QSysNetwork.swift,
portal-ios · Sources/QSysKit/QSysConfiguration.swift,
portal-ios · RiverOaksUtility/App/RiverOaksUtilityApp.swift,
infrastructure/service-timeline · src/service_timeline/client.py,
infrastructure/lyric-follower · macos/WorshipDataCaptureApp/Sources/WorshipDataCaptureApp/CommsPublisher.swift.
3. One API request, hop by hop
sequenceDiagram
participant C as Staff client
participant W as API Worker
participant V as Fixed VPC service
participant P as Portal PHP adapter
participant D as Portal SQL
C->>W: Allowlisted resource + bearer
W->>W: Lane/path/method/size/rate checks
W->>V: Sanitized request + request ID
V->>P: Configured Portal Host and adapter path
P->>D: Token/account/current permission checks
D-->>P: Authorized data
P-->>W: Adapter response
W-->>C: Sanitized response + request/release IDs
This sequence is for PHP-backed resources; direct Worker and Tasks routes have
separate handlers. Sources: portal-api · src/index.ts,
portal · dashboard/api/mobile/v1/lib/runtime.php.
4. Signing in (iOS app)
sequenceDiagram
participant A as Native app
participant W as API Worker
participant P as Portal / Google sign-in
participant K as Device Keychain
A->>W: Browser authorize, state + S256 challenge
W-->>P: Redirect to matching Portal auth/start.php
P-->>A: Callback code + state
A->>W: Token exchange + verifier
W->>P: token.php
P-->>A: Access + rotating refresh tokens
A->>K: Device-only token storage
Sources: portal-ios · RiverOaksPortal/App/WebAuthenticationService.swift,
portal-ios · RiverOaksPortal/App/KeychainTokenVault.swift, portal-api · src/index.ts,
portal · dashboard/api/mobile/v1/token.php.
5. How the web Portal uses the API (server-side BFF)
sequenceDiagram
participant B as Browser
participant P as Portal BFF / PHP session
participant A as Matching canonical API
B->>P: Session-authenticated page request
P->>P: Connect/callback, server-held OAuth tokens
P->>A: Allowlisted resource + bearer
A-->>P: Authorized JSON
P-->>B: Rendered page / BFF response
Source: portal · dashboard/v2/api/lib/client.php,
portal · dashboard/v2/api/callback.php.
6. Live ticket queue updates
sequenceDiagram
participant B as Browser
participant P as Portal BFF
participant A as API Worker
participant H as TicketLiveHub
B->>P: CSRF-protected live-token request
P->>A: Server-held bearer
A->>P: Validate Portal identity/permission
A-->>B: Signed short-lived connect token
B->>A: Exact Origin / WebSocket subprotocol credentials
A->>H: Connect after validation
H-->>B: Generic tickets.changed + revision
B->>P: Refetch authorized content, polling fallback
Sources: portal · dashboard/v2/tickets/api/live-token.php,
portal-api · src/index.ts, portal-api · src/ticket-live.ts,
portal-api · src/ticket-live-hub.ts, portal · docs/ticket-portal-live-updates.md.
7. Alerts: from a fault to a phone
flowchart LR
Source["Q-SYS / Grafana / monitor"] --> Sign["Publisher-specific signing"]
Sign --> API["API alert-ingest"] --> Policy["Portal publisher policy / RBAC / preferences"]
Policy --> Inbox[("Portal alert records")]
Inbox --> Foreground["Native alert fetch / wait"]
Inbox --> Sender["Portal APNs sender"] --> Apple["Apple push"]
Foreground -.-> LAN["Optional dev LAN alert proxy"]
Sources: infra · nodered/instances/telegram/qsys-portal-alert.js,
portal · dashboard/api/mobile/v1/lib/alert-ingest.php,
portal · scripts/mobile-apns-worker.php, portal-ios · Sources/PortalCore/APIClient.swift.
8. Tasks gateway (development only)
sequenceDiagram
participant C as Native client
participant A as Dev API
participant P as Dev Portal bootstrap
participant T as Tasks service binding
C->>A: Portal bearer / explicit task route
A->>P: Current active staff identity
P-->>A: Validated identity
A->>T: Short-lived request-bound assertion
T->>T: Tasks authorization / task version
T-->>C: Validated task result via API
Sources: portal-api · src/index.ts, portal-api · docs/TASKS.md,
portal-api · infra/modules/portal-platform/main.tf.
9. Live lyric path (not behind the API)
flowchart LR
PP["ProPresenter"] --> Poll["PHP poller"] --> Cache[("Shared RAM cache")]
Cache --> WS["Ratchet :8081"] --> Display["Displays / iPads"]
WS --> Follower["Loopback shadow observer :8094"]
PP --> Follower
QRC["Q-SYS LTC"] --> Follower
Follower --> Proposal["Evidence / proposal; live trigger disabled"]
WS --> Proxy["Private nginx /ws"] --> Browser["LAN browser"]
Sources: portal · lyrics/poll_propresenter.php,
portal · lyrics/server.php, infrastructure/lyric-follower · systemd/ro-lyric-shadow.service,
infrastructure/lyric-follower · src/lyric_follower/pp_agent.py,
infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf.
10. Comms and panic feed through the API
flowchart LR
Mac["Transcription feature-branch publisher"] -->|"HMAC snapshot"| API["Dev API"]
API --> PHP["Portal verify / ordering"] --> RAM[("Lane RAM snapshots")]
RAM --> WS["Opt-in comms WebSocket frames"] --> Pad["iPad panel"]
RAM --> HTTP["Private nginx JSON aliases"] -.->|"REST fallback"| Pad
PHP -.->|"signed-in GET comms"| Pad
Sources: infrastructure/lyric-follower · macos/WorshipDataCaptureApp/Sources/WorshipDataCaptureApp/CommsPublisher.swift,
portal · dashboard/api/mobile/v1/lib/comms.php,
portal · lyrics/comms_feed.php,
portal-ios · RiverOaksServiceDashboard/Models/DashboardModels.swift,
infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf.
Opt-in is not authorization; see privacy boundary.
11. Sermon slide pipeline
flowchart LR
Upload["Portal upload"] --> Drive["Drive / private cache"]
Upload --> Outbox[("Version / outbox records")]
Outbox --> Extract["Extraction worker"] --> Deliver["Presentation worker"]
Drive --> Extract
Deliver --> Receiver["Constrained Mac receiver / import"]
Drive --> Original["Worship Keynote destination"]
Receiver --> Notify["Notification / telemetry"]
Sources: portal · dashboard/v2/sermon-slides/process-upload.php,
portal · scripts/sermon-slide-extraction-worker.py,
portal · scripts/sermon-slide-propresenter-worker.py,
portal · scripts/sermon-propresenter-receive.py,
portal · scripts/sermon-worship-receive.sh.
12. Where each public hostname goes
flowchart LR
APIHost["api.ro.church / dev-api.ro.church"] --> API["Canonical staff Worker"]
API -->|"fixed VPC"| Origin["Matching Portal nginx vhost"]
PublicWeb["Portal / public lyric hostnames"] -.->|"external routing chain needs verification"| Origin
Forms["Forms entry"] --> FW["Forms Worker / D1 / R2 / Queue"]
Links["Short-link entry"] --> LW["Short Links Worker / D1"]
Congregation["Congregation app"] --> CW["Separate content/alerts Worker"]
Docs["docs.ro.church"] --> Pages["Pages / Access boundary"]
Sources: portal-api · infra/environments/alpha/main.tf,
portal-api · infra/environments/production/main.tf,
infra · nginx/hosts/rocc-db/sites-enabled/ro.church.conf,
cloudflare-forms · src/index.ts, cloudflare-short-links · src/index.ts,
church-app · services/alerts-api/src/worker.ts, docs · README.md.
External host routes are not proved solely by these origin/Worker definitions.
13. LAN-only names
flowchart LR
LAN["LAN / VPN client"] --> ACL["Private nginx source ACL"]
ACL --> Lyrics["lyrics.riveroaks.cc /ws and feed routes"]
ACL --> Songs["songs.riveroaks.cc"] --> Auth["Authentik"]
ACL --> Control["Lyrics Control browser routes"] --> Auth
ACL --> IPad["Exact iPad control POST exceptions"]
Capture["Bearer-authenticated capture client"] --> Special["Separate capture scheduling route"]
Sources: infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf,
infra · nginx/hosts/rocc-db/sites-enabled/songs.riveroaks.cc.conf,
infrastructure/lyric-follower · server/planning_center_api.py.
Capture scheduling explicitly differs from anonymous LAN/dashboard access.
14. Release order across repositories
flowchart LR
Origin["1. Portal dev adapter + schema"] --> Edge["2. API dev contract + smoke"]
Edge --> App["3. iOS dev / controlled device acceptance"]
App --> Accept["4. Accept with safe data"]
Accept -.->|"approved web/API promotion"| P["5. Portal main"]
P -.-> A["6. API main / production gate"]
Accept -.-> Native["Native production release is separate"]
This is the recommended compatibility order. Sources:
portal · .gitlab-ci.yml, portal-api · .gitlab-ci.yml,
portal-ios · .gitlab-ci.yml, portal-api · docs/MIGRATION.md.
15. What breaks if X is down
flowchart TB
Edge["API / VPC unavailable"] --> Staff["Staff API and BFF data unavailable"]
Edge --> Comms["New comms publication unavailable"]
Origin["rocc-db unavailable"] --> Shared["Portal origin + shared lyric/control services fail"]
PP["ProPresenter unavailable"] --> Fresh["New lyrics/countdown observations unavailable"]
Collector["Timeline collector unavailable"] --> Spool["Local spooling within configured capacity"]
APNs["Apple push unavailable"] --> Background["Background notifications delayed / absent"]
Failure impact is inferred from the source graph, not an outage test. Sources:
portal-api · src/index.ts, portal · lyrics/poll_propresenter.php,
infrastructure/lyric-follower · systemd/ro-lyric-shadow.service,
infrastructure/service-timeline · src/service_timeline/spool.py,
portal · scripts/mobile-apns-worker.php.
See runbooks and first checks.