{"slug":"architecture/ARCHITECTURE_LOCK","title":"IntegrateWise — Architecture Lock v1.1","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/ARCHITECTURE_LOCK.mdx","bytes":41311,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status**: SUPERSEDED — absorbed into INTEGRATEWISE_ARCHITECTURE.md v2.1. Implementation details amended by\n[`IMPLEMENTATION_CONTRACT_v1.1.md`](IMPLEMENTATION_CONTRACT_v1.1.md); runtime\nterminology clarified by\n[`CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md`](CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md)\n**Original freeze**: July 17, 2026\n**v1.1 clarification**: July 28, 2026\n**Source**: Code excavation of `integratewise-live` codebase\n\n---\n\n# I. PLATFORM CANON\n\n## The 12 Kernel Terms\n\n| Term           | Definition                                                                                                     | Owner        |\n| -------------- | -------------------------------------------------------------------------------------------------------------- | ------------ |\n| **WORK**       | A human or machine is moving an objective through state                                                        | Spine        |\n| **CONTEXT**    | The minimum relevant connected state required to understand current work                                       | Continuity   |\n| **SPINE**      | The canonical connected model of operational work state                                                        | Spine        |\n| **CONTINUITY** | The preservation and bounded transfer of relevant context across time, systems, humans, and agents             | Bridge       |\n| **WORKBENCH**  | The role-specific projection of work and context presented to a human                                          | Product      |\n| **TWIN**       | The non-authoritative cognitive participant that consumes grounded context                                     | Intelligence |\n| **CAPABILITY** | A registered operation that may read, derive, or change work state                                             | MCP Pool     |\n| **GOVERNANCE** | The authority that determines whether a capability or proposed consequence is permitted                        | Governance   |\n| **HERMES**     | The execution coordinator for authorized capability invocations                                                | Execution    |\n| **SYNC**       | The reconciliation of resulting state across connected systems                                                 | Sync         |\n| **BRIDGE**     | The governed exchange boundary through which an authorized consumer receives or contributes bounded continuity | Bridge       |\n| **OUTCOME**    | The observed result of work or execution that may become new canonical state                                   | Spine        |\n\n## The OODA Grammar\n\n| OODA        | Action                    | Meaning             |\n| ----------- | ------------------------- | ------------------- |\n| **Observe** | **Store in Spine**        | Capture truth       |\n| **Orient**  | **Ask Your Twin**         | Understand the work |\n| **Decide**  | **Assign Your Twin**      | Delegate intent     |\n| **Act**     | **Approve Twin's Action** | Authorize execution |\n\n## The Frozen Laws\n\n1. **Twin Law**: Twin is a capability of the Workbench, not a panel.\n2. **Context Law**: The human never explains already-known work context to AI.\n3. **Memory Law**: Spine owns truth. Memory informs truth. Memory is not truth.\n4. **Authority Law**: Confidence increases trust. Confidence never grants authority.\n5. **Silence Law**: Twin prefers silence over low-value commentary.\n6. **Capability Law**: Workbench projects tool capabilities, doesn't duplicate tools.\n7. **Bridge Law**: One platform. One boundary. Different projections.\n8. **Product–Platform Law**: Broad underneath. Narrow at the surface.\n\n## The Runtime Sequence (Frozen)\n\n```\nConfiguration\n    ↓\nIntegration\n    ↓\nPipeline\n    ↓\nAdaptive Spine\n    ↓\nWorkbench Composition\n    ↓\nContinuity Bridge\n    ↓\nUser Workbench\n    ↓\nTwin\n    ↓\nCapability\n    ↓\nGovernance\n    ↓\nHermes\n    ↓\nSync\n    ↓\nPromotion\n```\n\n## The Go-Live Sequence (Frozen)\n\nGo-live promotes the same verified Product and Platform versions through three\nisolated environments:\n\n```text\nDevelopment proof\n→ Customer Zero validation\n→ Customer Production release\n```\n\nThe mandatory promotion sequence is:\n\n```text\nsource commit\n→ CI and contract tests\n→ Development artifacts\n→ Customer Zero private installation\n→ Customer Zero evidence\n→ version freeze\n→ external clean-tenant test\n→ Plugin and MCP submission-ready\n→ public publication\n```\n\n| Phase                               | Required result                                                                                                                                                           |\n| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Shared contracts**                | Freeze the exact 19 public tools, resource schemas, UI intents, discovery envelope, tenant binding contract and versioned activation profiles.                            |\n| **Customer Zero Plugin**            | Privately install the focused embedded UI and prove identity, host composition, explicit delegation, approval, Hermes execution and outcome reconciliation.               |\n| **Customer Zero MCP and Workbench** | Deploy the OAuth-protected remote MCP, verify exactly 19 tools, prove ordinary-client fallback, launch the browser Workbench and verify discovery-first RBAC projections. |\n| **Externalization**                 | Install the same artifacts into a clean external tenant and prove dynamic tenant resolution, customer-owned connectors and complete Customer Zero isolation.              |\n| **Publication**                     | Freeze compatible versions, submit the Plugin, publish the MCP, verify a new-tenant installation and operate governed monitoring, rollback, revocation and deprecation.   |\n\n### Go-Live Laws\n\n1. **Same-Artifact Law**: Customer Zero and external customers use the same build with server-selected profiles. Do not create Product forks.\n2. **One-Way Promotion Law**: Promote only code, manifests, definitions, schemas and versioned activation defaults. Never promote tenant data, credentials, connector bindings, queues, caches, evidence, audit records or runtime state.\n3. **Customer Zero Proof Law**: Customer Zero must run daily work through both the Plugin and browser Workbench before external publication.\n4. **Clean-Tenant Law**: The frozen Customer Zero-verified versions must install into an unrelated tenant without code changes or Customer Zero-only dependencies.\n5. **Governed Execution Law**: Every external action requires a scoped human approval token, Hermes execution, audit evidence and outcome reconciliation into the Spine.\n6. **Compatibility Law**: The release manifest records compatible Plugin, MCP, frontend, Gateway and Platform versions and the last compatible rollback set.\n\n### Stop-Ship Gate\n\nDo not begin external testing or publication if environment isolation, tenant\nauthority, the exact 19-tool contract, clean installation, connector lifecycle,\nprojection/RBAC enforcement, governed execution, reconciliation, observability,\nrevocation or rollback lacks live evidence. The detailed evidence gates are\ndefined in\n[`CUSTOMER_ZERO_TO_EXTERNAL_PRODUCT_AND_MARKETPLACE_SPEC.md`](CUSTOMER_ZERO_TO_EXTERNAL_PRODUCT_AND_MARKETPLACE_SPEC.md#18-customer-zero-exit-gates)\nand\n[`CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md`](CONSOLIDATED_PRODUCT_PLATFORM_CONTRACT_v1.2.md#15-testing-environment-event-gate).\n\n## The GTM Marketplace Model (Frozen)\n\nGo-to-market (GTM) is the complete path from discovery to retained governed\nvalue. A marketplace listing is one acquisition mechanism within that path.\n\nIntegrateWise has three marketplace surfaces with different jobs:\n\n| Marketplace               | GTM role                                       | Published or activated item                                                                   | Primary experience                                                                                                                    |\n| ------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| **Plugin Marketplace**    | External acquisition and embedded activation   | **IW-Spine-Network Plugin**                                                                   | A focused MCP-backed UI, skills and approvals inside an AI host. The host controls conversation and model orchestration.              |\n| **MCP Marketplace**       | External acquisition and tool-first activation | **IW-Spine-Network MCP**                                                                      | The exact 19 public tools, meaningful text/JSON fallback, optional widgets and launch into the full browser Workbench.                |\n| **Connector Marketplace** | In-product capability activation and expansion | A tenant-scoped provider `Connection`, connector binding, schema mapping and capability grant | Users connect, reuse, monitor, revoke and replace operational systems inside IntegrateWise. It does not install IntegrateWise itself. |\n\nPlugin and MCP marketplaces distribute IntegrateWise. Connector Marketplace\nexpands what an activated IntegrateWise workspace can observe and govern. They\nconverge on the same tenant, Workspace, Adaptive Spine, Gateway, public tool\nsemantics and governed execution path.\n\n```text\nCategory and demand\n→ Plugin Marketplace, MCP Marketplace or direct Workbench activation\n→ identity, tenant, consent and workspace activation\n→ Connector Marketplace connection or eligible connection reuse\n→ Spine hydration and role projections\n→ first grounded value\n→ first approved governed outcome\n→ additional connectors, roles and recurring use\n```\n\nThe shared north-star metric is **time to first approved governed outcome**.\nChannel metrics diagnose that path:\n\n- Plugin and MCP marketplaces: listing view → install → `active`\n- Connector Marketplace: discover → consent → bind or reuse → healthy → hydrated\n- Product: first grounded response → first approval → reconciled outcome → recurring use\n\nProvider or developer marketplaces may require a channel-native package, OAuth\nlifecycle or webhook contract. That package is a distribution adapter over the\nsame Product and Platform contracts, not a fourth product or a new source of\ntruth.\n\n---\n\n# II. PLATFORM ARCHITECTURE\n\n## The Four Planes\n\n```text\n┌─────────────────────────────────────────────┐\n│  EXPERIENCE PLANE                           │\n│  User Workbench · Twin · Admin · Mobile     │\n│  AI Chat · Model Selector · Agent Canvas    │\n├─────────────────────────────────────────────┤\n│  INTELLIGENCE PLANE                         │\n│  Hermes · Knowledge · Memory · Signals      │\n│  Model Gateway · Omni Router                │\n├─────────────────────────────────────────────┤\n│  EXECUTION PLANE                            │\n│  Gateway · MCP Pool · Provider MCP          │\n│  Integration MCP · Task MCP                 │\n├─────────────────────────────────────────────┤\n│  FOUNDATION PLANE                           │\n│  Adaptive Spine · Identity · Security       │\n│  Storage · Timeline · Provenance            │\n└─────────────────────────────────────────────┘\n```\n\n## The Gateway (Entry Point)\n\n**Service**: `services/gateway/` (46 files)\n**Domain**: `gateway.dev.integratewise.ai`\n**Canonical truth**: Neon Postgres  \n**Bounded edge state**: D1 `integratewise-spine-cache`\n\n### Env Bindings (Frozen)\n\n| Category     | Binding          | Type        |\n| ------------ | ---------------- | ----------- |\n| **Database** | DB               | D1Database  |\n| **KV**       | RATE_LIMITS      | KVNamespace |\n| **KV**       | SESSIONS         | KVNamespace |\n| **KV**       | CONNECTOR_STATUS | KVNamespace |\n| **KV**       | SIGNAL_CACHE     | KVNamespace |\n| **KV**       | METRICS          | KVNamespace |\n| **KV**       | OAUTH_STATE_KV   | KVNamespace |\n| **R2**       | FILES            | R2Bucket    |\n| **Services** | CONNECTOR        | Fetcher     |\n| **Services** | CONNECTOR_SYNC   | Fetcher     |\n| **Services** | PIPELINE         | Fetcher     |\n| **Services** | INTELLIGENCE     | Fetcher     |\n| **Services** | KNOWLEDGE        | Fetcher     |\n| **Services** | BFF              | Fetcher     |\n| **Services** | L2               | Fetcher     |\n| **Services** | AGENT_RUNTIME    | Fetcher     |\n| **Services** | ADMIN            | Fetcher     |\n| **Services** | BILLING          | Fetcher     |\n| **Services** | TENANTS          | Fetcher     |\n| **Services** | WEBHOOK_INGRESS  | Fetcher     |\n| **Services** | HUB_CONTROLLER   | Fetcher     |\n\n### Gateway Route Table (Frozen)\n\n| Route                         | Target               | Purpose                  |\n| ----------------------------- | -------------------- | ------------------------ |\n| `/api/v1/auth`                | INTERNAL_AUTH        | Authentication           |\n| `/api/v1/projections`         | INTERNAL_PROJECTIONS | Projection Engine        |\n| `/api/v1/billing`             | INTERNAL_BILLING     | Billing                  |\n| `/api/v1/tenants`             | INTERNAL_TENANTS     | Tenant management        |\n| `/api/v1/support`             | INTERNAL_SUPPORT     | Support                  |\n| `/api/v1/analytics`           | BFF                  | Analytics                |\n| `/api/v1/agents`              | INTELLIGENCE         | Agent management         |\n| `/api/v1/continuity-bridge`   | MCP_CONNECTOR        | Public 19-tool Spine MCP |\n| `/api/v1/connectors`          | CONNECTOR            | Connector management     |\n| `/api/v1/pipeline`            | PIPELINE             | Data pipeline            |\n| `/api/v1/intelligence`        | INTELLIGENCE         | Intelligence layer       |\n| `/api/v1/cognitive/spine`     | PIPELINE             | Spine operations         |\n| `/api/v1/cognitive/entity360` | PIPELINE             | Entity 360               |\n| `/api/v1/cognitive/memories`  | KNOWLEDGE            | Memory operations        |\n| `/api/v1/cognitive/signals`   | INTELLIGENCE         | Signal processing        |\n| `/api/v1/cognitive/think`     | INTELLIGENCE         | Think/Twin               |\n| `/api/v1/cognitive/act`       | INTELLIGENCE         | Act execution            |\n| `/api/v1/cognitive/govern`    | INTELLIGENCE         | Governance               |\n| `/api/v1/cognitive/twin`      | AGENT_RUNTIME        | Twin runtime             |\n| `/api/v1/knowledge`           | KNOWLEDGE            | Knowledge management     |\n| `/api/v1/workspace`           | BFF                  | Workspace operations     |\n| `/api/v1/l2`                  | L2                   | L2 cognitive overlay     |\n| `/admin`                      | INTERNAL_ADMIN       | Admin operations         |\n| `/oauth`                      | INTERNAL_AUTH        | OAuth flows              |\n| `/ws`, `/sse`, `/stream`      | BFF                  | Real-time connections    |\n\n### Model Gateway Routes (Added)\n\n| Route                      | Target        | Purpose                       |\n| -------------------------- | ------------- | ----------------------------- |\n| `/api/v1/models`           | MODEL_GATEWAY | Model registry & selection    |\n| `/api/v1/models/providers` | MODEL_GATEWAY | Provider management           |\n| `/v1/chat/completions`     | MODEL_GATEWAY | OpenAI-compatible chat        |\n| `/v1/completions`          | MODEL_GATEWAY | OpenAI-compatible completions |\n| `/v1/embeddings`           | MODEL_GATEWAY | Embeddings                    |\n| `/v1/images/generations`   | MODEL_GATEWAY | Image generation              |\n| `/v1/audio/transcriptions` | MODEL_GATEWAY | Audio transcription           |\n| `/v1/audio/translations`   | MODEL_GATEWAY | Audio translation             |\n\n### Omni Router Routes (Added)\n\n| Route                     | Target      | Purpose                   |\n| ------------------------- | ----------- | ------------------------- |\n| `/api/v1/omni/tools`      | OMNI_ROUTER | Tool registry & discovery |\n| `/api/v1/omni/execute`    | OMNI_ROUTER | Tool execution            |\n| `/api/v1/omni/connectors` | OMNI_ROUTER | Connector management      |\n| `/api/v1/omni/stats`      | OMNI_ROUTER | Execution statistics      |\n\n---\n\n# III. CAPABILITY FABRIC\n\n## MCP Pool\n\n**Service**: `services/mcp-pool/` (14 files)\n**Capabilities**: 55 registered\n**Pattern**: Registry → Resolver → Health → Routing → Versioning\n\n### Registered MCPs\n\n| MCP                    | Capabilities                                             | Status   |\n| ---------------------- | -------------------------------------------------------- | -------- |\n| Provider Management    | 15 (`provider.*`, `apps.*`, `connections.*`, `oauth.*`)  | ✅ Built |\n| Integration Management | 28 (`connectors.*`, `sync.*`, `webhooks.*`, `schemas.*`) | ✅ Built |\n| Task Management        | 12 (`tasks.*`)                                           | ✅ Built |\n\n### Capability API\n\n```ts\npool.register(manifest, targetBinding);\npool.resolve({ capability, version });\npool.invoke({ capability, version, args, context });\npool.health();\npool.capabilities();\n```\n\n## Provider Management MCP\n\n**Service**: `services/provider-management-mcp/` (15 files)\n**Capabilities**: 15\n\n| Domain          | Capabilities                                       |\n| --------------- | -------------------------------------------------- |\n| `provider.*`    | list, health                                       |\n| `apps.*`        | list, get, create                                  |\n| `connections.*` | list, get, connect, delete, status, invoke, health |\n| `oauth.*`       | start, callback, status                            |\n\n## Integration Management MCP\n\n**Service**: `services/integration-management-mcp/` (10 files)\n**Capabilities**: 28\n\n| Domain         | Capabilities                                                             |\n| -------------- | ------------------------------------------------------------------------ |\n| `connectors.*` | install, configure, enable, disable, remove, get, list, providers, stats |\n| `sync.*`       | start, complete, cancel, retry, list, latest, stats                      |\n| `webhooks.*`   | register, pause, resume, remove, list, findByEvent, stats                |\n| `schemas.*`    | register, normalize, list, latest, entityTypes, diff                     |\n\n## Task Management MCP\n\n**Service**: `services/task-management/` (11 files)\n**Capabilities**: 12\n\n| Domain    | Capabilities                                                                                         |\n| --------- | ---------------------------------------------------------------------------------------------------- |\n| `tasks.*` | create, get, list, update, delete, pause, resume, runNow, history, getDue, markCompleted, markFailed |\n\n## Model Gateway (Added)\n\n**Service**: `packages/model-gateway/` (NEW)\n**Routes**: `/api/v1/models`, `/v1/chat/completions`, `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/transcriptions`\n**Providers**: llama.cpp, Hugging Face, OpenAI, OpenAI-compatible\n\n| Capability          | Endpoint                        | Description                          |\n| ------------------- | ------------------------------- | ------------------------------------ |\n| Model Registry      | `GET /api/v1/models`            | List all registered models           |\n| Provider Management | `GET /api/v1/models/providers`  | List all registered providers        |\n| Chat Completions    | `POST /v1/chat/completions`     | OpenAI-compatible chat               |\n| Completions         | `POST /v1/completions`          | OpenAI-compatible completions        |\n| Embeddings          | `POST /v1/embeddings`           | Text embeddings                      |\n| Image Generation    | `POST /v1/images/generations`   | Image generation (DALL-E compatible) |\n| Audio Transcription | `POST /v1/audio/transcriptions` | Speech to text (Whisper compatible)  |\n| Audio Translation   | `POST /v1/audio/translations`   | Translation (Whisper compatible)     |\n\n## Omni Router (Added)\n\n**Service**: `packages/omni-router/` (NEW)\n**Routes**: `/api/v1/omni/tools`, `/api/v1/omni/execute`, `/api/v1/omni/connectors`, `/api/v1/omni/stats`\n**Providers**: Salesforce, GitHub, Slack, MCP servers (via connector executors)\n\n| Capability           | Endpoint                           | Description                                   |\n| -------------------- | ---------------------------------- | --------------------------------------------- |\n| Tool Registry        | `GET /api/v1/omni/tools`           | List all available tools                      |\n| Tool Execution       | `POST /api/v1/omni/execute`        | Execute any tool via provider-agnostic router |\n| Connector Management | `GET/POST /api/v1/omni/connectors` | Register/manage connectors                    |\n| Execution Statistics | `GET /api/v1/omni/stats`           | Execution metrics & tracing                   |\n\n---\n\n# IV. ADAPTIVE SPINE\n\n## Canonical Entities\n\n| Entity            | Source                                      | Status   |\n| ----------------- | ------------------------------------------- | -------- |\n| **Connection**    | `packages/spine-entities/src/connection.ts` | ✅ Built |\n| **Connector**     | `packages/spine-entities/src/connector.ts`  | ✅ Built |\n| **SyncJob**       | `packages/spine-entities/src/sync-job.ts`   | ✅ Built |\n| **Webhook**       | `packages/spine-entities/src/webhook.ts`    | ✅ Built |\n| **Schema**        | `packages/spine-entities/src/schema.ts`     | ✅ Built |\n| **Capability**    | `packages/spine-entities/src/capability.ts` | ✅ Built |\n| **TimelineEvent** | `packages/spine-entities/src/timeline.ts`   | ✅ Built |\n\n### Entity Contract (Frozen)\n\nEvery entity owns:\n\n| Property          | Meaning                                           |\n| ----------------- | ------------------------------------------------- |\n| **identity**      | Canonical entity reference (id, provider, tenant) |\n| **fields**        | Structured attributes                             |\n| **relationships** | Connected entities                                |\n| **timeline**      | Temporal history (TimelineEvent)                  |\n| **provenance**    | Source and lineage                                |\n| **permissions**   | Access governance                                 |\n| **capabilities**  | Available operations                              |\n\n## Spine Service\n\n**Service**: `services/spine/` (scaffolded)\n**Store**: `EntityStore<T>` — generic CRUD with in-memory Map\n**Routes**: REST API for all 7 entity types\n\n| Route                  | Method   | Entity        |\n| ---------------------- | -------- | ------------- |\n| `/api/v1/connections`  | GET/POST | Connection    |\n| `/api/v1/connectors`   | GET/POST | Connector     |\n| `/api/v1/sync-jobs`    | GET/POST | SyncJob       |\n| `/api/v1/webhooks`     | GET/POST | Webhook       |\n| `/api/v1/schemas`      | GET/POST | Schema        |\n| `/api/v1/capabilities` | GET/POST | Capability    |\n| `/api/v1/timeline`     | GET/POST | TimelineEvent |\n| `/api/v1/stats`        | GET      | Entity counts |\n\n---\n\n# V. PRODUCT SURFACES\n\n## The Workbench\n\n> **The User Workbench is the role-specific projection of work and context presented to a human.**\n\nThe Workbench is **one surface**. No L1/L2/L4/L7 layers in the UI.\n\n### Sidebar = Capability Navigation\n\n```\n┌────────────────────────────────────────────────────────────┐\n│ Header                                                     │\n├──────────────┬─────────────────────────────────────────────┤\n│ Left Sidebar │                                             │\n│              │          Active Workspace                   │\n│              │                                             │\n│ ── Operational ──                                          │\n│ Home         │                                             │\n│ Accounts     │                                             │\n│ Contacts     │                                             │\n│ Meetings     │                                             │\n│ Tasks        │                                             │\n│ Calendar     │                                             │\n│ Docs         │                                             │\n│ Knowledge    │                                             │\n│ Analytics    │                                             │\n│              │                                             │\n│ ── Platform ──                                             │\n│ Continuity   │                                             │\n│ Governance   │                                             │\n│ Integrations │  (Integration Manager)                     │\n│ Configuration│  (Configuration Manager)                    │\n│ Activation   │  (Activation Hub)                           │\n│ Network Graphs│ (Spine relationship graph)                │\n│ Settings     │                                             │\n│              │                                             │\n│ Twin: NOT a sidebar item. It surfaces contextually,      │\n│       invoked by \"Ask your Twin\" / \"Assign your Twin\".    │\n│              │                                             │\n└──────────────┴─────────────────────────────────────────────┘\n```\n\n> **Platform section = the platform control surfaces.** Each is a real module\n> wired to the platform, not an architectural layer and not the Twin.\n>\n> - **Integrations** → Integration Manager (connectors, sync, webhooks, schemas)\n> - **Configuration** → Configuration Manager (tenant schema, depth matrix, policies)\n> - **Activation** → Activation Hub (onboarding completion, intelligence activation)\n> - **Network Graphs** → Spine entity relationship graph\n> - **Governance** → Approvals, audit, policy gates\n> - **Continuity** → Memory, context\n>\n> **Twin is silent by default.** It is NOT a permanent sidebar destination, panel, or layer.\n> It observes the pipeline continuously and surfaces only when there is material value\n> or when the user explicitly engages via the Four Buttons.\n\n### The User Never Sees Layers\n\n| ❌ Never in UI      | ✅ Always in UI   |\n| ------------------- | ----------------- |\n| \"Open L2\"           | \"Open Twin\"       |\n| \"Switch to L4\"      | \"Open Continuity\" |\n| \"Go to L7\"          | \"Open Governance\" |\n| \"Layer 1 Workbench\" | \"Open Home\"       |\n\n### Internal Architecture (invisible to user)\n\n```\nWorkbench (UI)\n    ↓\nContinuity (L4 — memory, context)\nGovernance (L7 — approvals, policies)\nTwin (L2 — cognitive overlay)\nSpine (SSOT)\nGateway (routing)\nMCP (capabilities)\n```\n\n### External Architecture (what user sees)\n\n```\nWorkbench\n```\n\n### Role Projection (sidebar per role)\n\n**Customer Success:**\n\n```\n── Operational ──\nHome, Accounts, Contacts, Meetings, Tasks, Calendar, Risks, Renewals, Analytics\n── Platform ──\nContinuity, Governance, Integrations, Configuration, Activation, Network Graphs, Settings\n(Twin is silent — surfaces contextually, not a nav item)\n```\n\n**Technology:**\n\n```\n── Operational ──\nHome, Repositories, Services, Deployments, Incidents, Knowledge, Analytics\n── Platform ──\nContinuity, Governance, Integrations, Configuration, Activation, Network Graphs, Settings\n(Twin is silent — surfaces contextually, not a nav item)\n```\n\n**Founder:**\n\n```\n── Operational ──\nAll operational modules (union of all roles)\n── Platform ──\nContinuity, Governance, Integrations, Configuration, Activation, Network Graphs, Settings\n(Twin is silent — surfaces contextually, not a nav item)\n```\n\n### Documentation Convention\n\n| Context              | Reference                                                                   |\n| -------------------- | --------------------------------------------------------------------------- |\n| **Product docs**     | Workbench, Operational Modules, Platform Capabilities, Twin, Adaptive Spine |\n| **Engineering docs** | L1 (Workbench), L2 (Cognitive), L4 (Memory), L7 (Governance)                |\n| **User-facing**      | Never mention L1–L7                                                         |\n\n### Domain Structure (from IW-CUS-ZERO)\n\n```typescript\ntype DomainId =\n  | \"integratewise-apac\" // Founder / Customer Zero\n  | \"personal\" // Personal workspace\n  | \"account-success\" // Customer Success\n  | \"revops\" // Revenue Operations\n  | \"salesops\"; // Sales Operations\n```\n\n### Domain Views (Account Success example — 17 views)\n\n```\ndomains/account-success/views/\n├── account-master-view.tsx\n├── api-portfolio-view.tsx\n├── business-context-view.tsx\n├── capabilities-view.tsx\n├── company-growth-view.tsx\n├── engagement-log-view.tsx\n├── initiatives-view.tsx\n├── insights-view.tsx\n├── people-team-view.tsx\n├── platform-health-view.tsx\n├── product-client-view.tsx\n├── risk-register-view.tsx\n├── stakeholder-outcomes-view.tsx\n├── strategic-objectives-view.tsx\n├── success-plans-view.tsx\n├── task-manager-view.tsx\n└── value-streams-view.tsx\n```\n\n### Workbench Components\n\n| Component            | File                                  | Size | Purpose                             |\n| -------------------- | ------------------------------------- | ---- | ----------------------------------- |\n| Workspace Shell      | `workspace-shell.tsx`                 | 11KB | Top-level layout, context switching |\n| L1 Module Content    | `l1-module-content.tsx`               | 57KB | Domain-specific module rendering    |\n| Onboarding Flow      | `onboarding/onboarding-flow.tsx`      | 26KB | Initial setup and activation        |\n| Intelligence Overlay | `intelligence-overlay.tsx`            | —    | L2 cognitive overlay                |\n| Command Palette      | `command-palette.tsx`                 | —    | Quick actions                       |\n| Twin UI              | `twin-ui/twin-shell.tsx`              | —    | Twin interface                      |\n| Governance Workbench | `governance/governance-workbench.tsx` | 21KB | L7 governance/approval              |\n| Continuity Shell     | `continuity/continuity-shell.tsx`     | —    | L4 memory hub                       |\n| Integrations Hub     | `integrations-hub.tsx`                | —    | Connector management                |\n\n### Context Types (CTXEnum)\n\n| Context         | Role                |\n| --------------- | ------------------- |\n| `CTX_CS`        | Customer Success    |\n| `CTX_SALES`     | Sales               |\n| `CTX_SUPPORT`   | Support             |\n| `CTX_PM`        | Project Management  |\n| `CTX_MARKETING` | Marketing           |\n| `CTX_BIZOPS`    | Business Operations |\n| `CTX_TECH`      | Technology          |\n| `CTX_HR`        | Human Resources     |\n| `CTX_FINANCE`   | Finance             |\n| `CTX_LEGAL`     | Legal               |\n\n### L1 Module Types\n\n```typescript\ntype L1Module =\n  | \"Home\"\n  | \"Projects\"\n  | \"Accounts\"\n  | \"Contacts\"\n  | \"Meetings\"\n  | \"Docs\"\n  | \"Tasks\"\n  | \"Calendar\"\n  | \"Notes\"\n  | \"Knowledge Space\"\n  | \"Team\"\n  | \"Pipeline\"\n  | \"Risks\"\n  | \"Expansion\"\n  | \"Analytics\"\n  | \"Integrations\"\n  | \"Ingress\"\n  | \"Schema Registry\"\n  | \"Governance\"\n  | \"Continuity\"\n  | \"Operations\"\n  | \"Admin\"\n  | \"AI Chat\"\n  | \"Settings\"\n  | \"Subscriptions\"\n  | \"Profile\";\n```\n\n### L2 Component Types\n\n```typescript\ntype L2Component =\n  | \"SpineUI\"\n  | \"ContextUI\"\n  | \"KnowledgeUI\"\n  | \"Evidence Drawer\"\n  | \"Signals\"\n  | \"Think\"\n  | \"Act\"\n  | \"HITL\"\n  | \"Govern\"\n  | \"Adjust\";\n```\n\n### Spine Integration\n\nThe Workbench reads from Spine via:\n\n- `useSpine()` — Spine client hook\n- `useDomainTable(domain, table)` — Domain-specific data\n- `useSpineProjection(context)` — Context projection\n- `useSpineReadiness()` — Spine readiness status\n\n### Backend Connection\n\n- `api-client.ts` — Direct fetch to `/api/*`\n- `workspace-api.ts` — Workspace-specific API calls\n- Gateway integration via `VITE_API_BASE_URL`\n\n---\n\n# VI. DATA FLOW (Canonical)\n\n## Source Documents\n\n- `docs/architecture/source/integratewise-data-flow.md` — Canonical data flow KT\n- `docs/architecture/source/code-map-appendix.md` — Code implementation map\n- `docs/architecture/source/product-service-offers.md` — Productized service offers\n- `docs/architecture/source/app-landing-page.md` — App landing page content\n\n## The Canonical Runtime Chain\n\n```\nLanding → Auth → L0 Onboarding → L1 Workspace → L2 Cognitive → L3 Backend\n```\n\n## The Canonical System Loop\n\n```\nLOAD → NORMALIZE → STORE → THINK → REVIEW & APPROVE → ACT → REPEAT\n```\n\n## The Four Flows\n\n| Flow       | Purpose                                                                                                                            | Canonical write boundary                                                                                |\n| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| **Flow A** | Structured operational entities, relationships, metrics, events and lifecycle state                                                | Deterministic normalization prepares candidates; governed writers/Pipeline promotion commit.            |\n| **Flow B** | Documents, communications, attachments, transcripts and unstructured evidence                                                      | Raw artifacts and extracted context retain provenance; promoted canonical records use governed writers. |\n| **Flow C** | AI sessions, model output, proposals, tool calls and candidate memory/knowledge/decisions                                          | Never writes operational truth directly; Triage proposes promotion.                                     |\n| **Flow D** | Identity, tenant, workspace, role, configuration, connection, credential-reference, capability, policy and runtime binding context | Governed Platform configuration writers only; Flow D is not a business-data partition.                  |\n\n**v1.1 correction:** approved external execution is not Flow D. It is the\ndownstream governed path:\n\n```text\nTwin or user intent\n→ Capability Fabric\n→ Governance\n→ Hermes\n→ execution provider\n→ provider outcome\n→ re-ingestion\n→ verification and reconciliation\n→ Pipeline promotion\n```\n\nFlow D supplies the authority and binding context used by that path.\n\n## Deterministic Normalization Functions\n\nThe current implementation may express these as eight stages. The functions and\ntheir deterministic boundary are normative; an internal stage count is not a\nseparate product concept.\n\n```\n1. Raw Event Ingestion\n2. Canonical Field Mapping\n3. Schema Normalization\n4. Entity Resolution\n5. Deduplication\n6. Relationship Linking\n7. Depth Matrix Evaluation\n8. Spine Write\n```\n\n## Core Principles\n\n1. **The Spine is the single source of truth** — all durable business value must be created through a Spine-based flow\n2. **No data may bypass the governed write path** — every canonical mutation passes through tenant, schema, provenance, idempotency and authority enforcement\n3. **Flow C never writes directly to the Spine** — knowledge and decision context only become truth through approved actions\n4. **The workspace is not a truth layer** — L1 is dynamically generated from Spine data, not a separate SSOT\n5. **No action executes without approval** — Think → Govern → HITL → Act / Adjust\n6. **Normalizer and Triage are separate** — Normalizer is deterministic; Triage is adaptive and cannot confer authority\n7. **A click is context, not authority** — clicks may refresh Active Context and passive observation, but visible Twin reasoning remains governed by the Silence Law\n\n## Desktop\n\n**App**: `apps/desktop/` (Electron + electron-vite)\n**Framework**: Electron wrapper\n**Routes**: 0 (wraps web app)\n**Backend**: Indirect (through web app)\n\n## Mobile\n\n**App**: `apps/mobile/` (Expo 52 + React Native 0.76)\n**Framework**: expo-router\n**Routes**: 4 tab routes (Dashboard, Signals, Playbook, Settings)\n**Backend**: Direct fetch to `/api/v1/*`\n**Status**: Scaffolded, no build output\n\n## Local Monitor\n\n**App**: `apps/local-monitor/` (Node.js daemon)\n**Framework**: Chokidar file watcher\n**Purpose**: Bridges local filesystem changes into pipeline\n**Backend**: POST to `/webhooks/folder-monitor`\n\n---\n\n# VI. DATA SUBSTRATE\n\n## Neon Postgres (Canonical)\n\nNeon owns canonical operational entities, relationships, lineage, governed\nartifacts, and promoted outcomes. Pipeline promotion is its sole writer.\n\n## D1 (Bounded Operational State)\n\n| Database                    | Binding      | Purpose                                                   |\n| --------------------------- | ------------ | --------------------------------------------------------- |\n| `integratewise-spine-cache` | DB (gateway) | Active context, idempotency, projections, runtime indexes |\n\n## KV (Hot Cache)\n\n| Namespace        | Binding          | Purpose                          |\n| ---------------- | ---------------- | -------------------------------- |\n| Rate Limits      | RATE_LIMITS      | API rate limiting                |\n| Sessions         | SESSIONS         | User sessions                    |\n| Connector Status | CONNECTOR_STATUS | Connector install/runtime status |\n| Signal Cache     | SIGNAL_CACHE     | Signal event cache               |\n| Metrics          | METRICS          | Application metrics              |\n| OAuth State      | OAUTH_STATE_KV   | OAuth flow state                 |\n\n## R2 (Blobs)\n\n| Bucket | Binding | Purpose                                    |\n| ------ | ------- | ------------------------------------------ |\n| Files  | FILES   | Files, attachments, evidence, raw payloads |\n\n---\n\n# VII. IDENTITY\n\n## Authentication Stack\n\n| Layer            | Provider                                     | Status       |\n| ---------------- | -------------------------------------------- | ------------ |\n| **Primary**      | Clerk                                        | ✅ Canonical |\n| **JWT**          | Clerk session validation + tenant membership | ✅ Canonical |\n| **OAuth**        | Google, GitHub, Slack, Salesforce, HubSpot   | ✅ Active    |\n| **MCP Auth**     | Cloudflare Access                            | ✅ Active    |\n| **Webhook Auth** | HMAC signature verification                  | ✅ Active    |\n\n---\n\n# VIII. FOUR CONNECTION PATHS\n\n| Path              | Purpose                                                          | Contract                        |\n| ----------------- | ---------------------------------------------------------------- | ------------------------------- |\n| **MCP**           | Connects tools and resource protocols                            | Tool protocol                   |\n| **AI Connector**  | Connects intelligence providers and AI runtimes                  | Intelligence provider contract  |\n| **API Connector** | Connects operational systems                                     | Provider integration contract   |\n| **API Wrapper**   | Converts existing callable operations into governed capabilities | Capability abstraction contract |\n\n---\n\n# IX. VERSIONING\n\n## Platform Version Rules\n\n| Change                     | Version       |\n| -------------------------- | ------------- |\n| New kernel concept         | Major (2.0)   |\n| New runtime step           | Major (2.0)   |\n| New doctrine               | Minor (1.1)   |\n| New capability type        | Minor (1.1)   |\n| Implementation improvement | Patch (1.0.1) |\n| New projection             | Patch (1.0.1) |\n| New role composition       | Patch (1.0.1) |\n\n## Current Status\n\n**Platform Lock: DECLARED**\n**Version: 1.0**\n**Status: FROZEN**\n\n---\n\n# X. TAGLINE\n\n> **Truth you own. AI you rent. Approval in between.**\n"}