{"slug":"architecture/ONBOARDING_FLOW","title":"The Onboarding Flow — Canonical (L0)","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/ONBOARDING_FLOW.mdx","bytes":8080,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Status:** Canonical architecture doctrine\n> **Date:** June 12, 2026\n> **Authority:** Nirmal (Founder)\n> **Companion docs:** `SPINE_MODEL.md` (the truth), `PROJECTION_MODEL.md` (views), `USER_SYSTEM_JOURNEY_BLUEPRINT.md` (L0)\n> **Map:** `docs/CANON.md`. When a doc contradicts this file or its referenced code, the code wins.\n\n**Canonical Reference:** [CANONICAL_PLATFORM_ARCHITECTURE.md](./CANONICAL_PLATFORM_ARCHITECTURE.md)\n\n> This document is downstream of the Canonical Platform Architecture. When this document contradicts the canonical architecture, the canonical architecture wins.\n\n---\n\n## 0. The one sentence that defines onboarding\n\n```text\nOnboarding does not assign a workspace.\nOnboarding creates a Spine Context.\nWorkspaces are projections computed from that Spine Context.\n```\n\nThis is the doctrine that prevents the `CUSTOMER_SUCCESS → Business Operations` confusion: a user\ndoes not \"land in a workspace.\" Onboarding resolves _who they are, what org they're in, what\nreality they connect, and how deep they see_ into a single **Spine Context**. Every surface they\nlater see is a projection of that context (see `PROJECTION_MODEL.md`).\n\nThe journey shifted from `Signup → Workspace → Dashboard` to:\n\n```text\nIdentity → Organization → Reality Connections → Spine Hydration\n        → Memory → Projection → Governance → Continuity → (Desk)\n```\n\n---\n\n## 1. What onboarding actually collects (code-grounded)\n\nThe L0 flow has **four UI steps** (`apps/web/src/components/activation/onboarding/`):\n\n```text\nWelcome  →  Profile  →  Goals  →  Connect\n```\n\nproducing one `OnboardingData` object (`OnboardingFlow.tsx`):\n\n```text\nuseCase: personal | work | business     industry, department, companySize\ngoal, workspaceName                      connectors: [{ provider, flowType: A|B|C }]\ncreamyJobId  (Spine-build job)           spineInitialized\n```\n\nTwo pure maps turn that into a **Spine Context**, not a workspace:\n\n- `USE_CASE_DOMAINS` — useCase + department → canonical domain (`CUSTOMER_SUCCESS`, `BIZOPS`,\n  `SALES`, `PRODUCT_ENGINEERING`, …). Same domains as `DOMAIN_SPINE_CONFIG`.\n- `DEPARTMENT_CTX_MAP` — department → operating context (`CTX_CS`, `CTX_BIZOPS`, `CTX_SALES`, …).\n\nThe UI steps are the _surface_; the constitutional phases below are the _system journey_ they drive.\n\n---\n\n## 2. The constitutional phases (L0 → Desk)\n\n| Phase                         | What happens                                                                                                                               | Grounded in                                             |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |\n| **1. Identity**               | Authenticate; establish the user (gateway credential auth, RS256 JWT).                                                                     | `WelcomeStep`, gateway `auth.ts`                        |\n| **2. Organization Discovery** | Resolve useCase + department + industry + size → canonical **domain** and **CTX\\_\\***.                                                     | `ProfileStep`, `USE_CASE_DOMAINS`, `DEPARTMENT_CTX_MAP` |\n| **3. Reality Connections**    | Connect the tools that hold the org's reality (Nango). Each connector is tagged Flow A/B/C.                                                | `ConnectorsStep`, `connectors[]`                        |\n| **4. Spine Hydration**        | Real data flows in; the 8-stage pipeline normalizes and writes the **Spine** (D1 partitions). The workspace arrives pre-filled, not empty. | `AILoader` (`creamyJobId`), `services/pipeline`         |\n| **5. Memory Activation**      | Conversational / org / personal memory begin accumulating via the continuity pipeline.                                                     | `services/continuity`                                   |\n| **6. Projection Generation**  | The Spine Context yields projections — nav, modules, entity views, metrics — per `PROJECTION_MODEL.md`.                                    | `lib/projection/*`, gateway projection endpoints        |\n| **7. Governance Activation**  | The HARD GATE is live: AI may think/propose, never act without approval (`x-approval-token`).                                              | `services/intelligence` / `govern`                      |\n| **8. Continuity Activation**  | Context is now shared across every AI, tool, and session — the IW Continuity Bridge is on.                                                 | `services/continuity`, `iw-agent-runtime`               |\n| **Exit: Desk**                | The user arrives at their projected workbench (L1) with the Spine already populated.                                                       | `spineInitialized: true` → workspace                    |\n\n`STEP_TIMINGS` budget the visible path to ~2 minutes; Spine hydration runs as a tracked job\n(`AILoader` polls `creamyJobId`) so the desk is populated, not blank.\n\n---\n\n## 3. Why this is not \"create a workspace\"\n\n```text\nWRONG:  signup → pick a workspace → fill it\nRIGHT:  resolve Spine Context (identity + org + reality + depth) → hydrate Spine → project surfaces\n```\n\nConsequences (all enforced elsewhere in the canon):\n\n1. **One context, resolved once.** `department`/persona is resolved a single time into the Spine\n   Context (canonical domain + `CTX_*`), never re-derived per surface. (`PROJECTION_MODEL.md` §5)\n2. **Surfaces are computed.** The \"workspace\" a user sees is a projection of the context, so the\n   same account renders correctly for a CS practitioner, a RevOps manager, and the founder.\n3. **Pre-filled, not empty.** Because Phase 4 hydrates the Spine from real connected data before\n   the desk opens, the first view has substance.\n4. **Continuity from minute one.** The context and memory created here are the same substrate every\n   future session, tool, and AI reads — that is the product.\n\n---\n\n## 4. Invariants\n\n- Onboarding writes a **Spine Context + hydrated Spine**, never a standalone workspace store.\n- Domains and contexts come from canonical maps (`DOMAIN_SPINE_CONFIG`, `USE_CASE_DOMAINS`,\n  `DEPARTMENT_CTX_MAP`) — no ad-hoc department strings.\n- All writes go through the pipeline to Cloudflare D1 (DECISION 22). No Supabase provisioning at\n  signup. (Migration status tracked in `docs/migrations/DE_SUPABASE_MIGRATION.md`.)\n- Governance is active before the user can act; the Twin is read-only to the Spine.\n\n---\n\n## 5. Source-of-truth index (read the code, not a copy)\n\n| Concept                                 | Authoritative source                                                               |\n| --------------------------------------- | ---------------------------------------------------------------------------------- |\n| Flow + data shape + domain/context maps | `apps/web/src/components/activation/onboarding/OnboardingFlow.tsx`                 |\n| UI steps                                | `.../onboarding/steps/{WelcomeStep,ProfileStep,GoalsStep,ConnectorsStep}.tsx`      |\n| Spine-build progress (hydration)        | `.../onboarding/AILoader.tsx`, `WorkplaceLoading.tsx`                              |\n| Domain config + department mapping      | `packages/types/src/schema.ts` (`DOMAIN_SPINE_CONFIG`, `DEPARTMENT_TO_CONFIG_KEY`) |\n| Pipeline (Spine hydration)              | `services/pipeline`                                                                |\n| Projection of the context               | `docs/architecture/PROJECTION_MODEL.md`, `apps/web/src/lib/projection/*`           |\n| L0 in the journey                       | `docs/architecture/USER_SYSTEM_JOURNEY_BLUEPRINT.md`                               |\n\n---\n\n_This file is the canonical reference for onboarding. Pointer-based by design. Onboarding creates a\nSpine Context; workspaces are projections of it. When in doubt — halt, ask Nirmal._\n"}