Example App Walkthrough

Copy Markdown View Source

The canonical current-state host fixture lives at examples/phoenix_host. The frozen historical source fixture for the supported upgrade lane lives at examples/phoenix_host_upgrade_source.

It is a curated fixture, not a fully generated demo app. It proves the supported paved road:

  1. generate a Phoenix host with mix phx.new
  2. add Oban Powertools as a dependency
  3. run mix oban_powertools.install
  4. keep the host seams explicit for auth, display policy, router scope, and seeded operator data

That paved road is the unified native /ops/jobs control plane plus the optional read-only /ops/jobs/oban bridge for generic inspection only.

Provenance

Read the fixture as three provenance buckets:

  1. mix phx.new generated the baseline Phoenix host.
  2. mix oban_powertools.install generated the Powertools wiring, route mount, and migration set.
  3. Manual host-owned follow-up keeps the auth seam, display-policy seam, and narrow support-truth seed lane explicit.

What the Fixtures Prove

examples/phoenix_host is the contract proof for the public docs path. It demonstrates:

  • a real router scope at /ops/jobs
  • the diagnosis-first overview and cross-surface audit destination as native control-plane pages
  • a real host-owned auth_module
  • a real host-owned display_policy
  • migrations generated by mix oban_powertools.install
  • seeded operator access for the canonical first successful session
  • the canonical proof values ops-demo, nightly_sync, and pause_cron_entry
  • the optional read-only /ops/jobs/oban bridge path when oban_web is present

examples/phoenix_host_upgrade_source is not a second canonical fixture. It exists only as the frozen pre-display_policy source host for the singular supported upgrade lane.

Why This Fixture Exists

The fixtures keep the docs honest. If the documented install path ever drifts from the real host shape, examples/phoenix_host is where that drift becomes visible first. If the documented upgrade lane drifts from the real supported source host, examples/phoenix_host_upgrade_source is where that drift becomes visible first.

How to Use It

Read the fixture when you want to compare your host app against the canonical curated shape. Reach for it when:

  • your router mount differs from the expected /ops/jobs scope
  • your auth or display policy integration is unclear
  • you want a concrete example of seeded operator access
  • you need to confirm the native-vs-bridge support boundary

Use the fixture alongside Installation and First Operator Session, not instead of them.

Forensics and Runbook Handoff

DOC05-C4: The supported fixture-backed continuity flow is: ops-demo runs pause_cron_entry for nightly_sync, confirms diagnosis context in /ops/jobs/forensics, then confirms follow-up visibility in /ops/jobs/audit.

DOC05-C5: Keep ownership labels explicit at the handoff point:

  • Powertools-native for native Audited action
  • Oban Web bridge for Inspection only
  • host-owned follow-up for downstream actions outside Powertools ownership

Treat evidence boundaries as authoritative:

  • partial evidence
  • history unavailable
  • unknown

For the canonical deep narrative and wording contract, see Forensics And Runbook Handoffs.