{"slug":"architecture/CANONICAL_ARCHITECTURE_SPEC","title":"IntegrateWise — Canonical Architecture Spec","section":"architecture","sectionLabel":"Architecture","status":"current","type":"document","path":"architecture/CANONICAL_ARCHITECTURE_SPEC.mdx","bytes":17599,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Version:** 1.0 | **Date:** 2026-08-23 | **Status:** ACTIVE SOURCE OF TRUTH\n> **Authority:** Nirmal (Founder)\n\n---\n\n## The Fundamental Loop\n\n```text\n          OBSERVE\n             │\n             ▼\n     BUSINESS CONTEXT\n             │\n             ▼\n          ORIENT\n             │\n             ▼\n       SELF-ORGANIZING\n          WORKSPACE\n             │\n             ▼\n           DECIDE\n             │\n             ▼\n       TWIN / HUMAN\n             │\n             ▼\n            ACT\n             │\n             ▼\n    SOURCE SYSTEM EXECUTION\n             │\n             ▼\n          RECORD\n             │\n             ▼\n       SPINE FABRIC\n             │\n             ▼\n        CONTINUITY\n             │\n             └──────────────► OBSERVE\n```\n\n---\n\n## 1. The Product Boundary\n\n### IntegrateWise\n\n**IntegrateWise is the company/brand.**\n\nIts product proposition is:\n\n**Business Context + Business Continuity across an organization's fragmented tool ecosystem.**\n\n### Spine Workspace\n\n**Spine Workspace is the product.**\n\nIt is:\n\n> **A self-organizing workspace where people and AI continue and complete work across the organization's authorized business systems without requiring the user to continuously switch tools and reconstruct context.**\n\nThat means the product is **not**:\n\n- another CRM\n- another project-management system\n- another chat application\n- another AI agent platform\n- another database\n- an operating system replacement\n\nIt is the **working surface and continuity layer across them**.\n\n---\n\n## 2. The Two Paths\n\n```text\n                    SPINE WORKSPACE\n                          │\n             ┌────────────┴────────────┐\n             │                         │\n       USER PATH                  SYSTEM PATH\n       Experience                 Execution / Runtime\n             │                         │\n             ▼                         ▼\n   What the user sees          How the system operates\n   and accomplishes            to make it possible\n```\n\n### User Path asks:\n\n> **What is the user trying to accomplish?**\n\n### System Path asks:\n\n> **What must happen across Spine, tools, intelligence, and execution to accomplish it?**\n\nDo not mix these two when defining repositories, features, routes, components, workflows, or services.\n\n---\n\n## 3. USER PATH\n\nThe User Path is the product experience.\n\nThe user should think in terms of **business work**, not infrastructure.\n\n```text\nUSER\n  │\n  ▼\nIntent / Business Need\n  │\n  ▼\nSelf-Organizing Workbench\n  │\n  ├── My Work\n  ├── Tasks\n  ├── Inbox\n  ├── Communications\n  ├── Accounts / Records\n  ├── Documents / Knowledge\n  ├── Approvals\n  ├── Activity\n  ├── Canvas\n  └── Twin\n  │\n  ▼\nContext appears automatically\n  │\n  ▼\nUser understands situation\n  │\n  ▼\nUser decides / requests / approves\n  │\n  ▼\nWork is performed\n  │\n  ▼\nUser sees outcome\n```\n\nThe user should **not** have to reason:\n\n```text\nWhich database?\nWhich connector?\nWhich MCP?\nWhich agent?\nWhich workflow?\nWhich provider?\nWhich model?\nWhich queue?\nWhich worker?\n```\n\nThose belong to the System Path.\n\n---\n\n## 4. User Path: Three Experience Layers\n\n### A. User Workbench\n\nThis is where humans actually work.\n\nIt contains:\n\n- personal view\n- work view\n- organizational context\n- tasks\n- communications\n- records\n- documents\n- knowledge\n- activity\n- approvals\n- business views\n- contextual actions\n- Twin interaction\n\nDifferent users get different views according to their role/work.\n\n### B. Twin\n\nTwin is not another destination the user must manage.\n\nThe user should effectively have:\n\n> **one primary AI relationship**\n\nThat relationship is Twin.\n\n```text\nUser\n  │\n  ▼\nTwin\n  │\n  ├── understands user context\n  ├── assembles business context\n  ├── reasons\n  ├── proposes\n  ├── delegates\n  ├── coordinates\n  └── reports outcome\n```\n\nTwin may use other agents, models, MCP, tools, workflows, capabilities — but those remain implementation/runtime mechanisms.\n\n### C. Agentic Workbench\n\nThis is the **machine-facing operational surface**.\n\nIt exists for:\n\n- agent runs\n- model interactions\n- task execution\n- delegated work\n- tool execution\n- agent state\n- workflow state\n- operational traces\n- reasoning context\n- execution monitoring\n\n```text\nHuman Work\n     ↓\nUser Workbench\n\n\nAI Work\n     ↓\nAgentic Workbench\n```\n\nTwin becomes the bridge between them.\n\n---\n\n## 5. SYSTEM PATH\n\nThe System Path begins whenever something enters or changes the ecosystem.\n\n```text\nIDENTITY\n   ↓\nINGESTION\n   ↓\nCONTEXT / MEMORY\n   ↓\nPROJECTION\n   ↓\nINTELLIGENCE\n   ↓\nCAPABILITY / EXECUTION\n   ↓\nSOURCE SYSTEM\n   ↓\nEVENT / RECEIPT\n   ↓\nSPINE\n```\n\n---\n\n## 6. System Path — Phase 1: Identity\n\nEverything starts with:\n\n```text\nUser / Agent / Tool\n        │\n        ▼\nOne Auth\n        │\n        ▼\nIdentity + Tenant + Authority\n```\n\n**Identity is not just an authentication feature.**\n\nIt establishes:\n\n- who\n- which tenant\n- which role\n- which authority\n- which capabilities\n- which data boundary\n- which actions are permitted\n\nThis becomes foundational to both paths.\n\n---\n\n## 7. System Path — Phase 2: Ingestion\n\n### Flow A — Structured Operational Data\n\n```text\nSource Tool\n    ↓\nConnector / Loader\n    ↓\nNormalizer\n    ↓\nContext extraction\n    ↓\nSpine\n```\n\n### Flow B — Unstructured Business Data\n\n```text\nSource\n   ↓\nLoader\n   ↓\nNormalizer / Parser\n   ↓\nSemantic/context extraction\n   ↓\nSpine\n```\n\n### Flow C — AI / Agentic Activity\n\n```text\nAI / Agent\n    ↓\nSpine interface\n    ↓\nMemory/context processing\n    ↓\nSpine\n```\n\n### Flow D — Identity / Authorization Gate\n\nFlow D is a **system prerequisite**, not a data type.\n\n```text\n               AUTHORITY / IDENTITY\n                       │\n          ┌────────────┼────────────┐\n          ▼            ▼            ▼\n       Flow A        Flow B       Flow C\n     Structured    Unstructured     AI\n          │            │            │\n          └────────────┼────────────┘\n                       ▼\n                 Loader/Normalizer\n                       │\n                       ▼\n                  Spine Fabric\n```\n\n---\n\n## 8. Spine Fabric\n\n**Spine Fabric is not one database.**\n\nIt is a collection of storage and memory mechanisms:\n\n```text\n                         SPINE FABRIC\n                              │\n        ┌─────────────────────┼─────────────────────┐\n        │                     │                     │\n  Canonical Truth       Operational Memory      Artifacts\n        │                     │                     │\n        │                     │                     ├── documents\n        │                     │                     ├── images\n        │                     │                     ├── audio\n        │                     │                     ├── video\n        │                     │                     └── attachments\n        │                     │\n        ├── entities          ├── events\n        ├── relationships      ├── context\n        ├── transactions       ├── embeddings\n        ├── KPIs               ├── semantic memory\n        └── business truth     └── active work state\n```\n\n> **Spine Fabric is the organization's persistent business-context substrate.**\n\nIt contains the **story of what has happened**, not merely snapshots of records.\n\n---\n\n## 9. Spine Has Two Logical Planes\n\n```text\n             SPINE FABRIC\n                  │\n       ┌──────────┴──────────┐\n       │                     │\n CANONICAL PLANE       OPERATIONAL PLANE\n       │                     │\n source-of-truth        working/contextual\n governed truth        projections + memory\n       │                     │\n protected             AI / agents / workspace\n       │                     │\n       └──────────┬──────────┘\n                  │\n             governed bridge\n```\n\n### Canonical\n\nProtects authoritative truth.\n\n### Operational\n\nMakes that truth usable by Workspace, Twin, agents, workflows, context assembly, search, projections, execution.\n\nDo **not** expose the canonical plane as the user's working interface.\n\n---\n\n## 10. Context Assembly\n\nContext assembly is a **first-class system operation**.\n\n```text\nBusiness Need / User Intent\n           │\n           ▼\n       Context Resolver\n           │\n           ├── User context\n           ├── Work context\n           ├── Organization context\n           ├── Entity context\n           ├── Event history\n           ├── Relevant documents\n           ├── Conversations\n           ├── Related transactions\n           ├── Policies\n           └── Available capabilities\n           │\n           ▼\n      Context Bundle\n           │\n      ┌────┴─────┐\n      ▼          ▼\n    Human      Twin\n     View      Reasoning\n```\n\n---\n\n## 11. What Makes the Workspace \"Self-Organizing\"\n\n> **The workspace organizes the relevant work, context, capabilities, and AI assistance around the user's current business need.**\n\nNot random UI rearrangement. Targeted assembly.\n\nExample:\n\n```text\nTask: Refund requested\n\nInstead of:\nGmail → Salesforce → Zendesk → Stripe → Slack → Notion → Excel → AI\n\nThe Workspace assembles:\nREFUND REQUEST\n├── Customer\n├── Account\n├── Contract\n├── Subscription\n├── Previous tickets\n├── Relevant emails\n├── Slack discussion\n├── Payment history\n├── Refund policy\n├── Previous decisions\n├── Current risk\n├── Recommended action\n├── Supporting evidence\n└── Twin\n```\n\n---\n\n## 12. Capability Assembly\n\nEach workspace state has two dynamically assembled dimensions:\n\n```text\nCONTEXT + CAPABILITY\n```\n\nExample:\n\n```text\nRefund Request\n\nContext:\n- customer history\n- payment history\n- support history\n- contract\n- policy\n- previous decisions\n\nCapabilities:\n- approve refund\n- reject refund\n- request review\n- reply to customer\n- update CRM\n- issue refund\n- create follow-up task\n```\n\n---\n\n## 13. Execution Path\n\n```text\nUSER\n  ↓\nWORKBENCH\n  ↓\nACTION / INTENT\n  ↓\nTWIN / GOVERNANCE\n  ↓\nCAPABILITY\n  ↓\nWORKFLOW / ORCHESTRATION\n  ↓\nSOURCE TOOL\n  ↓\nRESULT\n  ↓\nEVENT / RECEIPT\n  ↓\nSPINE\n  ↓\nUPDATED CONTEXT\n  ↓\nWORKBENCH\n```\n\nThe rule:\n\n> **Read context from Spine; execute against source systems; record the resulting event/receipt back into Spine.**\n\nNot: \"Everything executes inside Spine.\"\n\n---\n\n## 14. Where Agents Belong\n\nAgents are **workers inside the System Path**.\n\n```text\n                    TWIN\n                      │\n              delegates / coordinates\n                      │\n        ┌─────────────┼─────────────┐\n        ▼             ▼             ▼\n      Agent A       Agent B      Workflow\n        │             │             │\n        └─────────────┼─────────────┘\n                      ▼\n                 Capabilities\n                      │\n                      ▼\n                 Source Tools\n```\n\nThe user does not manage agents. Twin does.\n\n---\n\n## 15. MCP's Correct Position\n\nMCP is an **interoperability mechanism**, not the architecture.\n\n```text\nSpine Network / MCP\n        │\n        ├── expose context\n        ├── expose capabilities\n        ├── expose tools\n        └── expose continuity\n```\n\nThe architectural primitive is:\n\n**Spine capability/context network**\n\nnot:\n\n**MCP network**\n\nMCP is one transport/interface mechanism.\n\n---\n\n## 16. Complete Architecture\n\n```text\n                           INTEGRATEWISE\n                        BUSINESS CONTEXT\n                       + BUSINESS CONTINUITY\n                                  │\n                                  ▼\n                         ┌─────────────────┐\n                         │ SPINE WORKSPACE │\n                         │   PRODUCT       │\n                         └────────┬────────┘\n                                  │\n                    ┌─────────────┴─────────────┐\n                    │                           │\n               USER PATH                   SYSTEM PATH\n                    │                           │\n                    ▼                           ▼\n             User Workbench               Identity/Auth\n                    │                           │\n                    ▼                           ▼\n             Business Need                Connectivity\n                    │                           │\n                    ▼                           ▼\n          Contextual Workspace             Ingestion\n                    │                    A / B / C\n                    ▼                           │\n              Twin Interaction                ▼\n                    │                    Loader/Normalizer\n                    ▼                           │\n          Decision / Approval                  ▼\n                    │                    SPINE FABRIC\n                    ▼                           │\n              User Action               ┌──────┴──────┐\n                    │                   │             │\n                    │             Canonical       Operational\n                    │                   │             │\n                    │                   └──────┬──────┘\n                    │                          │\n                    │                    Context Assembly\n                    │                          │\n                    │                    Capability Fabric\n                    │                          │\n                    │                    Twin / Agents\n                    │                          │\n                    │                    Orchestration\n                    │                          │\n                    └──────────────────────► Execution\n                                               │\n                                               ▼\n                                        Source Systems\n                                               │\n                                               ▼\n                                      Events / Receipts\n                                               │\n                                               ▼\n                                          SPINE FABRIC\n                                               │\n                                               ▼\n                                      Updated Workspace\n```\n\n---\n\n## 17. Repository-Wide Ownership Model\n\n| Area                       | Owns                                                                          |\n| -------------------------- | ----------------------------------------------------------------------------- |\n| **Spine Workspace**        | User experience, workbench, projections, work surfaces                        |\n| **Spine Fabric**           | Business context, organizational memory, events, continuity                   |\n| **Context Assembly**       | Deciding what context is relevant                                             |\n| **Twin**                   | Primary AI representative, reasoning, delegation                              |\n| **Capability Fabric**      | What actions are available and under what authority                           |\n| **Integration Manager**    | Connections/authentication to external systems                                |\n| **Loader/Normalizer**      | Extracting and transforming source data into Spine-compatible representations |\n| **Workflow/Orchestration** | Executing multi-step operations                                               |\n| **Connectors/MCP**         | Transport/interface to external systems and AI environments                   |\n| **Governance**             | Policy, approval, authorization, evidence                                     |\n| **Source Systems**         | Actual domain execution and authoritative operational state                   |\n| **Agentic Workbench**      | AI operational visibility and execution environment                           |\n\n---\n\n## 18. One Canonical One-Liner\n\n> **Spine Workspace is the user-facing self-organizing workbench; Spine Fabric is the shared business-context and continuity substrate; Twin is the user's primary digital representative; capabilities and workflows execute authorized work through connected source systems; every resulting event returns to Spine so humans and AI can continue from the same evolving business truth.**\n\nThis is the **repo-wide conceptual spine**.\n"}