Onboarding Architecture — Near-Zero Backend Setup (2026-09-26)

Current path (too much backend)

Download tarball → extract → run from some folder (identity silently binds to that folder) → trial starts without telling the user when it ends → provider tokens via YAML/env → sync wiring → serve + tunnel for remote. Every step is a dropout point.

Target: mesh onboard (one command; five-minute normal-path target)

Required deployment modes, recovery behavior, and 44 edge-case acceptance scenarios are defined in Contract D of the canonical master gap plan. This document summarizes that contract; it is not a separate decomposition. Provider approval, MFA, and policy propagation can exceed five minutes.

  1. Anchor — mesh onboard asks where home is (default: current folder), writes the anchor, migrates any stray ./data DB into it. Running from a foreign folder afterward warns instead of silently forking identity (closes FM-GAP-07 in the dated master gap plan).
  2. Trial, out loud — prints the Pro trial expiry date and the buy link on day zero. No silent clocks.
  3. Providers by OAuth in the normal browser — select the deployment mode before authorization. Google native mode uses a publisher Desktop client, PKCE, and a local loopback callback. A remote/headless server uses a temporary local connection mode of the same mesh binary, securely paired to the exact server/project; it is not a permanent companion. Browser-only self-hosting uses a separately configured BYO Web client with the exact registered /auth/google-tasks/callback. Existing Asana web callbacks retain their own provider requirements. Credentials stay on the customer's installation, encrypted and behind account/connection-scoped auth references, never pasted into YAML. Native/pairing modes are planned work, not proven by the current BYO web-client intake implementation.
  4. First mesh from a template — pick A/B/C in plain words, get a working mesh with one synced list, not an empty shell.
  5. Surfaces lit — prints the exact URLs: local UI, Asana project, Google list, routine digest status. The user sees their first synced task before onboarding ends. Task creation requires explicit approval; read-only or declined proof is labelled accordingly, not called full synchronization success. Resume partially completed setup from durable state without duplicating remote lists or tasks.

Mode selection and exceptional paths

  • Local desktop: same binary plus normal browser; no customer Cloud project/client setup on the proposed publisher-native path.
  • Remote/private/headless: disclose the temporary browser-machine helper requirement. Never confuse server localhost with browser localhost or silently expose a private installation.
  • Browser-only/mobile/managed device: offer a configured BYO Web callback or a supported different-device path. If neither is available, return a typed blocked/unsupported result; do not invent a hosted broker.
  • Workspace restrictions: distinguish disabled Cloud API, disabled Tasks service, and blocked OAuth app/scopes. Separate admin consent; use an approved Tasks-enabled group and programmatic authorized member enrollment. The currently unsupported service-status toggle is a one-time admin bootstrap, not an action on every user connection.
  • Interruptions/security/credential failure: persist setup attempt, actor/project/server/account/client identity and expiry. Single-use state, PKCE, bounded retries, account isolation, encrypted storage, revoke, restore, and compensation follow Contract D.

Publisher app configuration/verification is a release responsibility, not work assigned to ordinary self-hosted customers. No shared confidential web-client secret is shipped in a binary or browser.

Decisions (owner)

  • D1: home-dir default data location with one-time CWD migration vs explicit anchor files. (Recommend: anchor + warn; servers keep CWD.)
  • D2: trial length stays 14 days (yes — matches pricing).
  • D3: mesh onboard ships inside the existing binary (no new download product); native/headless onboarding must be proven on the declared supported targets. Existing static builds do not prove OAuth callbacks, browser-machine pairing, or platform secret-store support.

Non-goals

No managed cloud signup, no account system, no hosted onboarding service. Self-hosted stays self-hosted — the wizard only removes typing, never adds a server.

Implemented surface (2026-10-27)

mesh onboard is built and is the only supported install path. It is flag-driven: no configuration file has to be written by hand.

mesh onboard --project "Flow Mesh" --task "Prove the mesh synchronizes" \
             --provider discord --credential-type bot_token \
             --credential-ref /etc/flow-mesh/discord-bot-token \
             --url https://mesh.example.com

Data root selection is FLOW_MESH_DATA_DIR (or --config), so a fresh install target is one environment variable away.

Verb Effect
mesh onboard Run or resume the five steps: identity, license, provider, project, first task
--diagnose Report the blocking step, its code, the stopped dependents, and the exact repair — read-only
--reconnect Replace a provider credential on a ready install; no second project or task
--revoke Remove a provider binding; project and tasks survive and the install stays ready

Properties the implementation holds, each covered by tests:

  • Resumable. A rerun resumes at the first incomplete step; completed steps are never repeated. Rerunning a ready install executes nothing.
  • Earliest-wins trial. A rerun cannot extend the trial window.
  • Bounded rollback. Each step declares the objects it owns; rollback undoes exactly those and refuses to proceed when a step owns objects with no compensator. A pre-existing operator project and the seeded _global project space survive.
  • Secrets by reference only. The credential is checked for existence and stored as ref:<path>. The value never enters the database, the report, or receipt output.
  • A revoked provider is not silently rebound by a later rerun.
  • Recovery is not a resume shortcut. --reconnect/--revoke refuse an install that never reached ready.

Two schema facts that constrain onboarding and are easy to get wrong: work_items.created_by and event_ledger.source_system accept only the enumerated source systems, provider_credentials.credential_type accepts only pat|oauth2|api_key|bot_token, and event_ledger.idempotency_key is NOT NULL and globally unique (not project-scoped). The first task's event derives its idempotency key from the work item, so a rerun collapses onto the same event instead of recording the task twice.

Note that an authority mode (static_credential, direct_oauth, workload_identity) is not a credential type. They are separate fields.

Proof

internal/e2e builds the real cmd/mesh binary and runs it as a subprocess against an isolated data root:

  • a clean install reaches its first synchronized task inside the five-minute budget, with one work_items row and one projected create event, and no config.yaml anywhere;
  • a second run executes nothing and creates no second task;
  • a failed install exits non-zero with status=blocked, blocked_at=provider, and an actionable repair string.

Generated from the Flow Mesh repository by scripts/build-docs-site.sh. If a page is wrong here, the file it was rendered from is wrong.