Skip to content

Portal origin server (rocc-db)

The reviewed IaC targets the Portal origin at 10.200.24.42:80; nginx serves separate production and development roots through PHP-FPM 8.1. Application code comes from riveroaks/portal; listeners and host service files are owned by riveroaks/infra. Sources: portal-api · infra/modules/portal-platform/main.tf, infra · nginx/hosts/rocc-db/sites-enabled/ro.church.conf, infra · deploy/targets/nginx/rocc-db.json.

How requests arrive

Entry point Origin behavior Evidence
Central API VPC service to fixed origin HTTP port; configured Host selects matching Portal vhost portal-api · src/index.ts, portal-api · infra/modules/portal-platform/main.tf
portal.ro.church /usr/share/nginx/portal/dashboard → PHP-FPM infra · nginx/hosts/rocc-db/sites-enabled/ro.church.conf
dev.portal.ro.church /usr/share/nginx/html/dev-portal/dashboard → PHP-FPM infra · nginx/hosts/rocc-db/sites-enabled/ro.church.conf
Public lyrics Exact static display pages; other paths denied/redirected as declared infra · nginx/hosts/rocc-db/sites-enabled/ro.church.conf
Private lyrics TLS, source ACL, WebSocket, narrow PHP/proxy routes and snapshot aliases infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf
Songs viewer Authentik-protected interactive viewer; separate LAN adapter remains available to dashboards infra · nginx/hosts/rocc-db/sites-enabled/songs.riveroaks.cc.conf, portal · lyrics/songs/api.php

These files establish listeners and application paths, not every public DNS, Tunnel, Access or upstream-proxy setting. The connector inventory/runbook is infra · docs/deploy/riveroaks-cloudflared.md; verify the external routing chain separately before changing it.

The Portal application (riveroaks/portal)

Path Responsibility Evidence
dashboard/api/mobile/v1/ Canonical API adapters; token/session validation, current account/RBAC portal · dashboard/api/mobile/v1/lib/runtime.php, portal · dashboard/api/mobile/v1/bootstrap.php
dashboard/v2/api/ Web BFF and OAuth callback portal · dashboard/v2/api/lib/client.php
dashboard/login/ Browser sign-in / Google integration portal · dashboard/login/google_login.php
lyrics/ Display poller, broadcaster, song adapter portal · lyrics/poll_propresenter.php, portal · lyrics/server.php, portal · lyrics/songs/api.php
database/, scripts/ Additive schema and worker/install/migration tooling portal · .gitlab-ci.yml

The PHP origin is the authority for Portal identity, permissions and business records. SQL data is not copied into the API Worker as a second authority. The API's ticket invalidation revision is a separate, limited state store. Sources: portal · dashboard/api/mobile/v1/lib/tokens.php, portal · dashboard/api/mobile/v1/lib/runtime.php, portal-api · src/ticket-live-hub.ts.

Databases and development boundary

Identity/RBAC and mobile tokens are SQL-backed; tickets, expenses and the budget have their own application database boundaries. Consult the isolation audit and migration code for actual targets instead of deriving a database name from the hostname. Sources: portal · docs/MOBILE_API.md, portal · scripts/verify-environment-database-isolation.php.

Development intentionally uses the production Technology budget ledger. The dev deploy audit permits shared databases (--allow-shared-database). A TestFlight build or a dev API hostname is therefore not authorization to create disposable budget entries. Other shared resources include the physical origin, PHP pool and VPC connector. Sources: portal · docs/technology-budget-sql-ledger.md, portal · .gitlab-ci.yml, portal-api · infra/modules/portal-platform/main.tf.

Background workers on rocc-db

Worker family Role Source
propresenter-poller, lyrics-websocket Slide/cache producer and Ratchet broadcaster infra · portal/hosts/rocc-db/files/etc/systemd/system/propresenter-poller.service, infra · portal/hosts/rocc-db/files/etc/systemd/system/lyrics-websocket.service
Lyrics watchdog Periodic health check and targeted recovery of lyric daemons infra · portal/hosts/rocc-db/files/etc/systemd/system/riveroaks-lyrics-watchdog.timer, infra · portal/hosts/rocc-db/files/usr/local/sbin/riveroaks-lyrics-watchdog
mobile-apns-* Alert push delivery portal · scripts/mobile-apns-worker.php, portal · scripts/systemd/mobile-apns-dev.service
sermon-slide-* Extraction, ProPresenter delivery, notification and telemetry portal · scripts/install-sermon-slide-workers.sh, portal · scripts/sermon-slide-propresenter-worker.py
Jamf OS updates Managed-device background workflow portal · docs/JAMF_OS_UPDATE_ASSISTANT.md
Files storage watch Storage health workflow portal · docs/files-storage-reliability.md
Ticket/Tasks sync Integration outbox processing portal · scripts/ticket-tasks-sync.php
Workflow health Freshness/failed-worker monitoring portal · scripts/workflow-health-watch.py

Unit/configuration presence proves intended execution, not that a specific timer is currently enabled or that its last execution succeeded. Verification belongs to the corresponding runbook.

Sermon-slide automation (one flow end to end)

Uploads enter the Portal workflow, which records versions/outbox work and uses Google Drive plus private cached content. Extraction builds slide data; the ProPresenter worker constructs/delivers presentations through a constrained receiver on the Mac. The original Keynote has a separate worship destination. Notification and telemetry workers track completion. 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, portal · scripts/sermon-slide-notification-worker.py.

The receiver imports/places content; content delivery must not be confused with triggering a live cue. See portal · docs/SERMON_PROPRESENTER_LIVE_DEPLOYMENT.md and portal · docs/SERMON_WORKFLOW_ALERT_RECOVERY.md before a recovery or replay. The architecture diagram is on Diagrams.

Deployment

dev targets /usr/share/nginx/html/dev-portal; main targets /usr/share/nginx/portal. CI handles checkout reconciliation, required schema apply/check steps and smoke verification. Review the lane's actual job rules: manual configuration jobs are not implied by a successful code deploy. Sources: portal · .gitlab-ci.yml, portal · .gitlab-ci.yml.

Lyric daemon activation is separate from copying PHP files: the helper restarts the long-running processes and verifies activity and WebSocket upgrade. Its normal guard defers on Sunday 07:00–13:30 and Wednesday/Thursday 18:00–21:30 (America/New_York), or while timecode/recording state is active. A force flag exists, so this is a normal-lane guard, not an unbypassable guarantee. Source: portal · .gitlab/activate-lyrics-services.sh.

Cloudflare Workers around the Portal

Forms, Email and Short Links have independent contracts, data and deployment lanes. Their detailed data flows and source links are in Clients and publishers.

Observability

The Portal observability runbook describes application/nginx buffers and Alloy shipping into Loki/Grafana. Use an opaque request ID to correlate an API error; do not paste request payloads, tokens, transcripts or personal data into a task. Sources: portal · docs/PORTAL_OBSERVABILITY.md, portal-api · src/index.ts.