Adoption Lab

FleetDesk is Rulestead's adoption lab — a realistic-but-minimal B2B fleet-ops host app you can run locally before wiring Rulestead into your own Phoenix app.

Domain: FleetDesk helps logistics teams dispatch drivers, monitor routes, and respond to operations alerts.

Use this guide when you want to see Rulestead working with realistic data and operator screens — not when you are ready to install into your app (that path is Getting Started and Installation).

At a glance

You are running three things:

1. FleetDesk — sample customer app. Flags change what dispatchers see.
2. Rulestead admin — where operators manage flags, rollouts, and kill switches.
3. Rulestead API — what both apps talk to.

Quick start (5 minutes)

1. From the repo root: scripts/demo/up.sh
2. Wait until postgres, redis, backend, and frontend are healthy (first boot usually takes one to three minutes).
3. Open FleetDesk at the frontend URL printed by the script → use View as to switch accounts → watch the map and dispatch headline change.
4. Open Rulestead admin at the admin sign-in URL printed by the script → kill enable-new-dashboard on staging.
5. Return to FleetDesk — the headline changes to Classic dispatch map is holding steady.
6. Optional: expand Developer tools on FleetDesk to see the explain trace and flag snapshots.

For automation only: scripts/demo/proof.sh.

What am I looking at?

These are the preferred default URLs. If those ports are already in use, scripts/demo/up.sh chooses free fallback ports and prints the actual URLs. Postgres and Redis stay on the internal Compose network by default.

Maintainers running several UI demos at once can use stable hostnames instead:

scripts/demo/proxy-up.sh

That reuses or starts the shared local Traefik proxy and prints the same three surfaces at .localhost URLs. The expected maintainer setup has no port in the browser URL. If an unrelated local process owns port 80, the script chooses a free loopback port and includes it in the printed URLs.

Optional API sanity checks:

curl http://localhost:4000/api/demo/personas
curl "http://localhost:4000/api/flags?env=staging&flag_key=enable-new-dashboard"

When using proxy mode, swap in the printed backend URL, usually http://rulestead.localhost.

Stack:

• examples/demo/backend/ — Phoenix host embedding rulestead + mounted rulestead_admin
• examples/demo/frontend/ — external Next.js app consuming flags through a custom OpenFeature web provider

Who this is for

The six flows in User Flows and JTBD map to concrete demo actions — FleetDesk is the runnable version of that mental model.

Persona click paths

Pick the path that matches your question. Each is a few minutes in the browser.

Evaluator — 5-minute adoption loop

1. Open http://localhost:3000 — note the storm advisory and dispatch workspace.
2. Switch View as to Morgan Chen · Acme Logistics (Enterprise) — map flips to vector v2.
3. Expand Developer tools and read the explain trace.
4. Open http://localhost:4000/demo/sign-in → kill enable-new-dashboard on staging.
5. Return to FleetDesk — headline changes to Classic dispatch map is holding steady.

Operator — admin feel

1. Open http://localhost:4000/demo/sign-in.
2. Browse flag inventory at /admin/flags?env=staging.
3. Open rollouts for fleet-map-v2 or dispatch-guarded-rollout.
4. Filter audit at /admin/flags/audit.

Support — explain one outcome

1. Open http://localhost:3000, expand Developer tools, and read the explain trace.
2. In admin, open simulate for enable-new-dashboard and compare the trace.

SRE — kill switch

1. Open http://localhost:4000/demo/sign-in.
2. Engage the kill switch for enable-new-dashboard on staging.
3. Confirm FleetDesk at http://localhost:3000 flips.
4. Review the audit timeline for the kill event.

When something doesn't load

• Run docker compose ps — are all four services healthy?
• Run scripts/demo/smoke.sh for automated health checks. It tears the stack down when it finishes unless you set DEMO_SMOKE_KEEP_STACK=1. Use scripts/demo/proof.sh for bounded automation without losing a stack you are clicking through.
• See FleetDesk demo (examples/demo) for Playwright and CI commands.

Two proof paths

Rulestead ships two complementary adopter proofs. Use both when you need maximum confidence before integrating.

Path A — FleetDesk (full stack, pre-installed)

Best for: evaluators, operators, and support personas who want a browser-ready system with seeded flags, accounts, and mounted admin.

From the repo root:

docker compose up --build

Running this alongside other local demos, or already have something on port 4000/3000? Use the wrapper instead — it auto-selects free ports, namespaces the Compose project, and prints the actual URLs:

scripts/demo/up.sh    # start (auto free ports)
scripts/demo/down.sh  # stop

For maintainer work across several local UI demos, use the proxy path. It keeps the app URLs stable and leaves Postgres/Redis internal:

scripts/demo/proxy-up.sh    # start at .localhost hostnames
scripts/demo/proxy-down.sh  # stop this demo stack

Honest boundary: FleetDesk is a pre-installed host. Compose builds an image that already ran mix rulestead.install and seeds. It proves host-shaped integration, not your app's first-hour installer run.

Bounded automation (smoke + contract tests, no browser):

scripts/demo/proof.sh

Full automation (smoke + Playwright — same as CI integration job):

scripts/demo/verify.sh

Path B — Fresh install journey (first-hour wiring)

Best for: Phoenix integrators validating mix rulestead.install → migrate → runtime wiring in an ephemeral host app.

scripts/demo/install_journey.sh

This reuses the golden-diff installer contract under rulestead/fixtures/install_golden/ and asserts generated Phoenix wiring. It does not boot FleetDesk or the Next.js frontend.

CI runs install-journey proof on the install_journey scoped lane (see Testing). Merge-blocking CI still uses FleetDesk smoke + mix verify.adopter.

Seeded fixtures

After mix run priv/repo/seeds.exs (also run by the compose entrypoint):

• Accounts: Jordan Lee (pro), Morgan Chen (enterprise), Riley Park (starter)
• Flags: enable-new-dashboard, fleet-map-v2, dispatch-ops-copy, ops-banner-config, dispatch-guarded-rollout, ops-audience-preview
• Environments: staging + production

Persona metadata: GET /api/demo/personas

Implementation detail lives in examples/demo on GitHub.

Journey map

Post-GA governance seeds use stub resolvers for guardrail and preview evidence. Sample cohorts and impression summaries are support-safe illustrations — not authoritative population counts (GOV-05 boundary).

Relationship to testing

• Unit and app tests: stay Fake-first — see Testing
• Host-shaped integration: FleetDesk + Playwright prove compose, admin mount, and browser glue
• Installer contract: install_journey.sh + golden-diff tests prove generated wiring
• Library contract: cd rulestead && mix verify.adopter unions post-GA band tests

Do not replace Fake-backed tests with Docker. Use the adoption lab when you need end-to-end confidence that mirrors a real host app.

Where to go next

• Install into your app: Getting Started
• Operator workflows: Admin UI
• Support traces: Explainability
• Product mental model: User Flows and JTBD