User journeys
Every user-facing flow, the surface that implements it, and the automated test that verifies it.
Every user-facing flow, the surface that implements it, and the automated test that verifies it. This is the completeness map: each story below maps to a working path.
Personas
- Developer / operator — integrates the product, works in the console and via the API.
- End customer — the SaaS's customer connecting their own domain, works in the widget.
- Platform operator — self-hosts and monitors the stack.
End-customer journeys (widget)
| # | As a customer, I want to… | Surface / path | Verified by |
|---|---|---|---|
| C1 | Enter my domain and have its DNS provider detected | Widget → Enter domain → Domain analysis (POST /v1/domains:check) | browser-e2e |
| C2 | Connect automatically when possible | Widget → Automatic setup (POST /v1/connections, delegated write) | it.sh (adapter path) |
| C3 | Get exact records to add when manual | Widget → Manual configuration (copy buttons) | browser-e2e |
| C4 | See progress until my domain is live | Widget → In progress (polls records:check) → Success | browser-e2e |
| C5 | Recover from errors / switch to manual | Widget → Error screen (retry / switch) | widget flow (widget.ts) |
| C6 | Not lose my place accidentally | Widget → exit-confirm + session-expired overlays | widget flow |
Developer journeys (console + API)
| # | As a developer, I want to… | Surface / path | Verified by |
|---|---|---|---|
| D1 | Create and manage applications | Console → Applications (list/create) + Application detail (edit) | console-smoke, it.sh (PATCH) |
| D2 | Create, list, and revoke API keys | Console → API keys / Application detail (POST/GET/DELETE keys) | it.sh (key lifecycle), console-smoke |
| D3 | Connect a domain from the console | Console → Domains → Connect a domain (POST /v1/connections) | console-smoke, it.sh |
| D4 | Inspect a connection and drive it | Console → Domain detail: verify, records:check, archive, DNS diff, cert | it.sh, console-smoke |
| D5 | Enable automatic DNS for an app | Console → Application detail → Delegated DNS credential | it.sh (adapter), console-smoke |
| D6 | See which providers auto-configure | Console → Providers grid (GET /v1/providers) | console-smoke |
| D7 | Receive events, inspect + replay deliveries | Console → Webhooks (register, log, replay) | it.sh (deliver/retry/replay), console-smoke |
| D8 | Track usage against quota | Console → Usage (GET /v1/usage) | console-smoke |
| D9 | View and change plan | Console → Billing (GET /v1/plans, /subscription, POST /v1/subscriptions) | console-smoke, it.sh (quota) |
| D10 | Embed the widget safely | POST /v1/tokens server-side; allowed_origins | it.sh, Widget SDK |
| D11 | Install the console as an app / use offline shell | PWA (manifest + service worker) | console-smoke (PWA assets) |
Platform-operator journeys
| # | As an operator, I want to… | Surface / path | Verified by |
|---|---|---|---|
| O1 | Run the whole stack locally | make dev | manual / e2e |
| O2 | Serve HTTPS for live domains automatically | Edge on-demand TLS gated by ask | e2e (real TLS) |
| O3 | Monitor health and cert-renewal risk | GET /metrics (Prometheus gauges) | it.sh (metrics) |
| O4 | Keep tenants isolated | Tenant-scoped handlers; cross-tenant → 404 | it.sh (isolation, IDOR guard) |
| O5 | Keep secrets safe | Encrypted credentials, no key material in logs | it.sh (log hygiene), unit tests |
Coverage note
Setup types semiautomatic, shared_login, async, and api exist in the data
model but are intentionally not built in the widget yet (documented in
Ownership and setup types). Everything
else above is implemented and exercised by the test suites listed.