{"slug":"internal/architecture/DETAILED_USER_FLOWS_AND_SYSTEM_PATHS","title":"Detailed User Flows and System Paths — IW Continuity Bridge (v3.7)","section":"internal","sectionLabel":"Internal","status":"unclassified","type":"document","path":"internal/architecture/DETAILED_USER_FLOWS_AND_SYSTEM_PATHS.mdx","bytes":11396,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Status: SUPERSEDED FLOW SNAPSHOT.** L0–L7 user layers, D1 domain\n> partitions, three-flow-only routing and Triage-as-writer claims are historical.\n> Use [`ARCHITECTURE_LOCK.md`](./ARCHITECTURE_LOCK.md) and\n> [`TENANT_SPINE_FORTRESS_OPERATIONAL_FLOW_MODEL.md`](./TENANT_SPINE_FORTRESS_OPERATIONAL_FLOW_MODEL.md).\n\n**Original Status:** Canonical reference\n**Last updated:** 2026-06-19  \n**Authority:** Extracted from architecture docs, session handoffs, code, and locked decisions (DECISIONS 18–27)  \n**Companions:** [USER_SYSTEM_JOURNEY_BLUEPRINT.md](USER_SYSTEM_JOURNEY_BLUEPRINT.md) (layers + stages overview + diagram), [WORKBENCH_DOCTRINE.md](WORKBENCH_DOCTRINE.md) (Workbench projection doctrine)\n\n---\n\n## Overview\n\n**User Flows (L0–L7):** What a human experiences.  \n**System Paths (S1–S12):** The invisible backend engine that makes it possible.\n\n**Core Invariants (locked):**\n\n- All data originates from or projects from the **Spine** (D1 domain partitions).\n- Every user, Twin, governance, knowledge, and domain surface is a **Workbench projection** over governed context.\n- No Workbench owns data, canonical truth, or system-of-record authority.\n- L7 is the **HARD GATE** — no execution without approval token.\n- Three data flows:\n  - **Flow A** (structured tools) — repeatable loop.\n  - **Flow B** (unstructured docs) — one-time normalization.\n  - **Flow C** (AI chat / Twin) — always HITL for writes.\n- Product is **100% Cloudflare** (D1 + KV + R2 + Vectorize + AI Search + DOs). Legacy Supabase references are migration-only.\n- Twin (L3) proposes / hands off playbooks. Never executes on behalf of customer (except Customer Zero ops).\n\n---\n\n## 1. User Flows (L0–L7) — Detailed\n\n### L0 — Onboarding (Spine Context Creation)\n\n**User Intent:** \"Connect my world so the AI actually knows my business.\"\n\n**Detailed Steps (4-step wizard in `apps/web/src/components/activation/onboarding/`):**\n\n1. **Welcome** — Choose useCase (personal | work | business).\n2. **Profile** — Industry, department, company size, role. Produces `activeDomain` (e.g. `CUSTOMER_SUCCESS`) and `CTX_*` context.\n3. **Goals** — Primary objective + workspace name.\n4. **Connect** — OAuth connectors (Nango/MCP). Tagged Flow A/B/C.\n\n**Outcome:**\n\n- `OnboardingData` → `initializeWorkspace({ domain })`\n- Spine Context created (`tenant_spine_config`)\n- 12×11 schema (domain base + industry overlay) resolved\n- \"Creamy\" initial hydration job started (30-day bounded load)\n- Active domain + preference stored in profile + JWT + localStorage\n\n**System Trigger:** S1 (Connectivity) → S2 (Loader) → S3 (Normalizer) → S5 (Spine Write)\n\n**Exit:** User lands at **L1 Workbench** with pre-populated data (not empty dashboard).\n\n**Personal vs Work:**\n\n- Personal always uses `PERSONAL` domain.\n- Work uses the chosen domain.\n\n### L0.5 — Always-On Operating Layer (Background)\n\n**User Intent:** Never sees this directly. \"The system just works and remembers.\"\n\n**What happens:**\n\n- `TwinAgent` DO: daily reflection cron (0 5 \\* \\* \\*)\n- `TenantBrainDO`: per-tenant signals, 15-min HITL timeouts, pause/resume\n- Folder Watcher DO + continuity watchers\n- Background normalization, memory promotion, audit logging\n\n**System:** S6 (Intelligence) + S7 (Memory) + S9 (Continuity) + S10 (Twin Runtime) + crons/DOs/Queues\n\n**Surfaces output:** Morning brief in L1, proposals in L2/L5/L7, context for L3.\n\n### L1 — User Workbench (Primary Daily Surface)\n\n**User Intent:** \"Show me my world, filtered to what matters right now.\"\n\n**Detailed Experience:**\n\n- Left nav: Personal + one Work domain (domain-specific modules).\n- `DOMAIN_CONTENT_MAP` + `LAYER_MODULES` (twin, memory, operations, execution, governance).\n- Creamy projections from Spine (`${domain}_data` via D1-direct or gateway).\n- Design tokens: `--iw-forest`, `--iw-gold`, `iw-` classes.\n- Entity tables, KPI strips, insights cards, quick actions.\n\n**Domain Differentiation:** L1 is the User Workbench projected through the active domain. L4 can also be domain-scoped. Everything else is a shared governed overlay or specialized Workbench projection.\n\n**Example (Customer Success domain):**\n\n- Accounts, Success Plans, At-Risk signals, Renewals, Initiatives.\n\n**System Path:** S4 (Entity Resolution) + S5 (Spine Write) + governed Workbench projections (gateway workspace-spine).\n\n**Data Rule:** Never raw connector data. Always Spine projection.\n\n### L2 — Intelligence Overlay (⌘J Awareness Drawer)\n\n**User Intent:** \"What should I pay attention to right now?\"\n\n**Detailed Experience:**\n\n- Global hotkey (⌘J) or sidebar trigger.\n- Signals strip (severity, entity-linked).\n- Insights panel, Think results, Govern queue, Evidence.\n- Filters by current L1 domain but can cross-scope.\n- Click → deep link to entity in L1 or proposal in L7.\n\n**System Path:** S6 (Intelligence) — signals, think, proposals. Reads from Spine + memory.\n\n### L3 — Twin Workbench (Reasoning Surface)\n\n**User Intent:** \"Talk to the AI that actually knows my context.\"\n\n**Detailed Experience:**\n\n- Full chat + reasoning blocks (not just bubbles).\n- Context seeds from L1 entities + L2 signals + L4 memory.\n- Proposes playbooks (never executes directly).\n- Voice (STT/TTS via @cloudflare/voice in DO).\n- Daily brief, reflection, proposals-in-context.\n\n**Hydration Flow (see Mermaid in blueprint):**\n\n1. Assemble continuity (conversational + org + personal memory).\n2. Activation gate (min memories + promoted count).\n3. Parallel search: aiSearch + conversationalSearch + mcpSearch.\n4. Engineering spine read if needed (D1 `build_data`).\n5. DO SQLite recent turns + learned_profile.\n6. Gateway chat (CF AI Gateway → OpenRouter or Workers AI fallback).\n7. Emit triage event for memory.\n\n**System Path:** S9 (Continuity Bridge) + S10 (Twin Runtime) + S6 (Intelligence).\n\n**Execution Boundary:** Twin outputs → proposal → L7 gate → L6 handoff.\n\n### L4 — Knowledge Workbench (\"Remember\")\n\n**User Intent:** \"Find or promote what the organization knows.\"\n\n**Detailed Experience:**\n\n- Semantic search across org_memory + promoted knowledge.\n- Documents, AI sessions, artifacts.\n- Promote / govern flow (staging → approved → published).\n- Domain-differentiated (Personal vs Work memory).\n\n**System Path:** S7 (Memory) + governance (S8).\n\n### L5 — Operations Workbench (\"Plan\")\n\n**User Intent:** \"What's happening and what needs planning?\"\n\n**Detailed Experience:**\n\n- Situations board, signals stream.\n- Proposal pipeline (draft → pending → approved).\n- Team / cross-functional views.\n\n**System Path:** S6 (Intelligence) + S8 (Governance).\n\n### L6 — Execution / Handoff Workbench (\"Execute\")\n\n**User Intent:** \"Approved work ready to run or hand off.\"\n\n**Detailed Experience:**\n\n- Approved queue, running executions, history.\n- Playbook viewer + status.\n- Writeback audit.\n\n**Two Paths (after L7 approval):**\n\n- **Customer Zero (internal):** Direct execution on Spine partitions.\n- **External Customer:** Export canonical Execution Package (JSON). Customer agent runs it. Outcome reported back via `/handoff/outcome`.\n\n**System Path:** S11 (Execution) + S12 (Writeback).\n\n**Hard Gate:** Requires `x-approval-token` from L7.\n\n### L7 — Governance Workbench (\"Govern\" — HARD GATE)\n\n**User Intent:** \"Review, approve, or reject AI proposals. See the full audit.\"\n\n**Detailed Experience:**\n\n- Pending approvals queue.\n- Policy editor.\n- Full audit trail (spine_audit_log + governance_data).\n- Approve → mints Execution Package + signature.\n\n**System Path:** S8 (Governance).\n\n**Non-negotiable:** No proposal becomes execution without explicit human approval here.\n\n---\n\n## 2. System Paths (S1–S12) — Detailed Backend Engine\n\nThe system is event-driven on Cloudflare (Workers + Queues + DOs + D1).\n\n### Ingestion & Truth (Flow A & B)\n\n**S1 — Connectivity**  \nConnectors (Nango, direct MCP, webhooks). OAuth flows. `services/connector`.\n\n**S2 — Loader**  \nRaw payload intake. Creamy (initial bounded) or delta sync. Sends to `pipeline-process` queue.\n\n**S3 — Normalizer (8-stage LLM-in-the-loop)**  \nImplemented in `services/pipeline`:\n\n1. Analyze (schema resolution from `tenant_spine_config`)\n2. Classify\n3. Filter (idempotency, schema membership)\n4. Refine (canonical names)\n5. Extract (only allowed fields)\n6. Validate\n7. Sanity Scan\n8. Sectorize (write to correct `${domain}_data` partition)\n\n**S4 — Entity Resolution**  \nDeduplication across connectors. Person/Company/Opportunity identity.\n\n**S5 — Spine Write**  \nWrite to D1 partitions (`decide_data`, `build_data`, `grow_data`, `run_data`, `cross_data`). Source of truth.\n\n### Intelligence & Action\n\n**S6 — Intelligence**  \nSignals, Think, Act. Generates proposals. `services/intelligence`.\n\n**S7 — Memory**  \nConversational, org, personal memory. Promotion via Triage Bot. `services/knowledge` + `services/continuity`.\n\n**S8 — Governance (HARD GATE)**  \nProposals, HITL queue, policies, signatures, audit. Only layer that can mint approval tokens.\n\n**S9 — Continuity Bridge**  \nAssembles full user/tenant context across memory + Spine + connectors.\n\n**S10 — Twin Runtime**  \n`services/iw-agent-runtime` (Durable Objects: TwinAgent, TenantBrainDO, TwinSessionDO). Context hydration, reasoning, proposal generation. CF Agents SDK.\n\n### Execution & Learning\n\n**S11 — Execution**  \nApproved proposals → playbook dispatch or direct run (Customer Zero only).\n\n**S12 — Writeback**  \nRecord outcomes, update Spine, emit memory events, close the loop.\n\n---\n\n## 3. End-to-End Example Flows\n\n### Onboarding Flow (L0 → L1 Desk)\n\n1. User completes L0 wizard → `initializeWorkspace`\n2. S1–S2: Connectors registered + creamy job queued\n3. S3–S5: Normalizer processes → Spine populated\n4. S7 + S9: Memory + Continuity start accumulating\n5. Projections generated → L1 Workbench appears pre-filled\n6. L0.5 background jobs activate\n\n### Daily Intelligence + Twin Loop (L1 → L2 → L3 → L7 → L6)\n\n1. L1 shows domain dashboard (Spine projections).\n2. L2 (⌘J) surfaces signals from S6.\n3. User opens L3 Twin → hydrated context (S9 + S10).\n4. Twin reasons → creates proposal (S6 → S8).\n5. User goes to L7 → reviews + approves (mint token).\n6. L6 shows approved item → handoff or execute (S11/S12).\n7. Outcome → memory promotion (S7) → future context improved.\n\n### Governance Enforcement (Always)\n\n- Any proposal path must hit L7.\n- No `x-approval-token` = execution blocked.\n- All actions logged to `spine_audit_log` + governance_data.\n\n---\n\n## 4. Key Design Rules & Data Invariants\n\n- **Projections only** — UI never sees raw connector tables.\n- **Domain scoping** — L1/L4 differentiated; L2/L3/L5/L6/L7 shared overlays.\n- **Execution Boundary** — Twin proposes. Customer (or Customer Zero) executes.\n- **Triage Bot** — Sole writer to promoted memory.\n- **Audit Everything** — Spine access + proposals produce immutable logs.\n- **CF Native** — All runtime state in D1/KV/DOs/Queues. No dual-write.\n\n---\n\nThis document is the detailed expansion of the high-level layers and stages. It is derived from the locked blueprint, end-to-end docs, flow traces, handoffs, and code. When in doubt, code + this file + `USER_SYSTEM_JOURNEY_BLUEPRINT.md` + `WORKBENCH_DOCTRINE.md` are authoritative.\n\nFor visual overview, see the Mermaid diagram in the blueprint.\n"}