Skip to content

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.