Atlas: Tenant Onboarding Milestones (NUX)
Snapshot: 2026-10-20. Shipped. All four PRs merged to arda-frontend-app main on 15–16 October 2026; PDEV-1830 closed as done; one follow-up ticket (PDEV-2150) in backlog; one reviewer question left open on #1422 by design.
This page is the map of the effort. New to the project? Read the Goal, then the Specification, then come back here to find where each piece landed.
Phases at a glance
Section titled “Phases at a glance”A single phase, one repository, one umbrella ticket.
| Phase | Umbrella ticket | Status | Scope |
|---|---|---|---|
V1 — milestones on Tenant.settings | PDEV-1830 | Done (2026-10-20) | BFF onboarding package, item create via BFF, onboarding provider, guide UI and kit fulfilment |
| Follow-up — per-tenant shipping codes | PDEV-2150 | Backlog (Low) | Replace the shared free-shipping code with single-use codes minted per tenant |
The PR stack
Section titled “The PR stack”Four stacked PRs on arda-frontend-app, each based on the one below it, merged bottom-up from #1438. #1438 and #1441 are independent of each other in content (the package, and the item-create route) but were stacked for review order; #1443 needs both; #1422 needs #1443.
Increment traceability
Section titled “Increment traceability”| Increment | Ticket | PR | Status | Design anchors |
|---|---|---|---|---|
@arda-cards/bff/onboarding: allowlisted vocabulary, GET milestones, POST milestone, POST item, POST starter-kit; recordMilestone first-wins and the completion gate | PDEV-1830 | #1438 | merged 2026-10-15 | DQ-M1, DQ-M2, DQ-M3, DQ-M4, DQ-M6 |
Every item add through useAddItem / useAddItems, calling the BFF item route; the method sent only for an enrolled tenant, read at call time | PDEV-1830 | #1441 | merged 2026-10-15 | DQ-M5 |
OnboardingProvider from useTenantOnboarding, useNuxEngagement, useAutoOpenGuide; tenant age from the account load; SignInMarker; workspace-switch discards in-flight answers | PDEV-1830 | #1443 | merged 2026-10-16 | Product rules: eligibility latch, auto-open once per sign-in |
Guide modal, header meter, celebration, kit sheet; useClaimStarterKit + useStarterKitFulfilment; nux-completed on the card walk’s startProcessing; read-time reconciliation; mock parity and scenario picker | PDEV-1830 | #1422 | merged 2026-10-16 | Product rules: goal, offer window, kit claim, completion; free shipping (revised 2026-10-12) |
| Project documentation: goal, as-built specification, atlas | PDEV-1830 | documentation #204 | open — awaiting review | — |
Decisions and where they landed
Section titled “Decisions and where they landed”| Decision | Recorded in | Implemented by |
|---|---|---|
DQ-M1/M2 — milestones live on Tenant.settings, written only by the BFF via read-merge-PUT; nothing recorded once nux-completed is held | Specification § Decision Summary | #1438 (milestonesStore.ts) |
| DQ-M3 — the kit’s identity is a sibling setting by entity id, not a name | Specification § Decision Summary | #1438 (claim), #1422 (completion check) |
| DQ-M4 — allowlisted key vocabulary; any key enrols, so arbitrary keys are not writable | Specification § Decision Summary | #1438 |
DQ-M5 — milestones recorded off actual feature use, over the created item; item-added-email on click-out is the one exception | Specification § Decision Summary | #1441, #1422 |
DQ-M7 — creationChannel on Item descoped from NUX | Specification § Decision Summary; PDEV-1830 | — (backlog) |
| One goal (25 items); the offer window never closes; pre-NUX tenants see nothing | Specification § Product rules | #1443, #1422 |
Completion is the card’s startProcessing (checkout finished), not accept (checkout opened); decided and recorded server-side, no client watch | Specification § Product rules, § Accepted trade-offs (4) | #1422 (kanbanCardHandler.ts, nuxCompletion.ts) |
| Free shipping via a standing Shopify code on the cart permalink, decoupled from the rung-3 reward (2026-10-12) | Specification § Product rules; PDEV-1830 | #1422; per-tenant codes → PDEV-2150 |
| Collections own the create and the claim; onboarding owns only policy | Specification § V1 write path | #1441 (useAddItem), #1422 (useClaimStarterKit) |
Design sources
Section titled “Design sources”- This directory: Goal, Specification (the as-built record, including the retained graduation-path design for a dedicated accounts module).
- PDEV-1830’s description carries the as-shipped scope and the 2026-10-12 decoupling note; the PR descriptions on #1438–#1422 carry the per-PR changelogs.
- Review history: Copilot’s per-push re-review and Michael Probber’s review on #1441/#1443/#1422 shaped the final shape (server-side completion, the completion gate, collections-owned claim). Every thread is answered on the PRs.
Related and parked
Section titled “Related and parked”- PDEV-2150 — per-tenant single-use shipping codes. Parked as Low: the shared code covers an $8 postage waiver on a $0 product; attribution rests on buyer-editable cart attributes, which is acceptable until the offer is worth gaming.
- Read-time reconciliation in
GET /bff/onboarding/milestones— not in the agreed design; kept pending the reviewer’s call (thread left open on #1422 deliberately). Lifts out cleanly if ruled against. - Server-side idempotency for a simultaneous kit claim — two users crossing the goal in the same instant can both claim before either remembers. No ticket; named in the specification’s trade-offs.
item-added-emailrecorded by the import itself — retires the client-observed click-out. No ticket.- DS Button
asChilddropsclassName— ux-prototype ticket candidate; link-outs work around it withbuttonVariants. - SupportToolKit 48h welcome-kit producer overlaps this offer — product call (Kyle), outside this project.
creationChannelitem provenance — the original PDEV-1830 plan; separate backlog item, no ticket yet.
Companion views
Section titled “Companion views”None. This page is canonical.
Copyright: © Arda Systems 2025-2026, All rights reserved