{"slug":"architecture/MULTI_PROTOCOL_PLATFORM","title":"IntegrateWise Platform Architecture — Multi-Protocol Platform","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/MULTI_PROTOCOL_PLATFORM.mdx","bytes":10154,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nThis document defines the canonical architecture for IntegrateWise as a multi-protocol platform.\n\n---\n\n## Core Principle\n\nIntegrateWise is not a single REST or GraphQL API. It is a **multi-protocol platform**.\n\n```\n                    IntegrateWise\n                ┌──────────────────┐\n                │ UI Protocol      │\n                ├──────────────────┤\n                │ Capability       │\n                ├──────────────────┤\n                │ Spine Network    │\n                ├──────────────────┤\n                │ Events           │\n                ├──────────────────┤\n                │ MCP              │\n                └──────────────────┘\n```\n\nEach protocol has distinct responsibilities and consumers.\n\n---\n\n## The Three Protocols\n\n### 1. UI Protocol\n\n**Purpose:** Read-heavy, UI-oriented interactions for applications like Customer Zero.\n\n**Consumers:**\n\n- Customer Zero web app\n- Marketplace\n- Admin dashboard\n- Mobile apps\n\n**Example methods:**\n\n```typescript\nworkbench.get();\nentity360.get();\nsearch.query();\nnotifications.list();\ntimeline.get();\nprojection.get();\n```\n\n**Characteristics:**\n\n- Session-oriented\n- Read-heavy\n- Projection-driven\n- UI-optimized response shapes\n\n---\n\n### 2. Capability Protocol\n\n**Purpose:** Governed execution of business actions.\n\n**Consumers:**\n\n- Customer Zero\n- Twin\n- MCP Pool\n- CLI tools\n- Automation workflows\n\n**Example methods:**\n\n```typescript\ncapability.execute({\n  capability: \"crm.account.create\",\n  params: { name: \"Acme Corp\" },\n});\n\ncapability.invoke();\ncapability.describe();\nregistry.find(\"crm.account.create\");\n```\n\n**Characteristics:**\n\n- Execution-oriented\n- Governed by policies\n- Two-gate approval\n- Event-producing\n- NOT for reading data\n\n---\n\n### 3. Spine Network Protocol\n\n**Purpose:** Canonical operational memory and continuity.\n\n**Consumers:**\n\n- Projection Engine\n- Capability Engine\n- Connector Runtime\n- Schema AI\n- MCP Pool\n- Entity360\n\n**Example methods:**\n\n```typescript\nspine.resolveEntity(id);\nspine.subscribe(entityId);\nspine.continuity(sessionId);\nspine.remember(memory);\nspine.context(tenantId);\nspine.observe(query);\nspine.link(sourceId, targetId, relation);\nspine.promote(entityId);\n```\n\n**Characteristics:**\n\n- Memory-oriented\n- Subscription-based\n- Continuity-first\n- NOT a CRUD API\n- NOT a UI API\n- NOT a capability execution API\n\n---\n\n## Protocol Boundaries\n\n```\nCustomer Zero\n    │\n    ├── UI Client ──────────────┐\n    │                          │\n    ├── Capability Client ─────┤\n    │                          │\n    └── Spine Client ──────────┘\n                              │\n                              ▼\n                        Gateway\n                              │\n              ┌───────────────┼───────────────┐\n              │               │               │\n         UI Service    Capability Service  Spine Service\n              │               │               │\n              └───────────────┼───────────────┘\n                              │\n                        Adaptive Spine\n```\n\n**Rule:** No protocol bypasses its designated service. The UI client never directly executes capabilities. The capability client never directly reads workbench projections.\n\n---\n\n## SDK Structure\n\nInstead of one monolithic SDK, split by protocol:\n\n```\n@integratewise/sdk                    ← umbrella/primary package\n@integratewise/ui-client              ← UI Protocol\n@integratewise/capability-client      ← Capability Protocol\n@integratewise/spine-client           ← Spine Network Protocol\n```\n\n### Primary Entry Point\n\nMost developers install one package:\n\n```bash\npnpm add @integratewise/sdk\n```\n\n```typescript\n\nconst platform = createPlatformClient({\n  endpoint: \"https://gateway.dev.integratewise.ai\",\n  token: INTEGRATEWISE_API_TOKEN,\n  tenantId: INTEGRATEWISE_TENANT_ID,\n});\n\n// UI Protocol\nconst workbench = await platform.ui.workbench.get(\"SALES\");\nconst searchResults = await platform.ui.search.query({ q: \"Acme\" });\n\n// Capability Protocol\nconst result = await platform.capabilities.execute({\n  capability: \"crm.account.create\",\n  params: { name: \"Acme Corp\" },\n});\n\n// Spine Protocol\nconst entity = await platform.spine.resolveEntity(\"acc_123\");\nawait platform.spine.remember({ type: \"semantic\", content: {...} });\n```\n\n### Advanced Usage\n\nAdvanced consumers can install sub-packages:\n\n```bash\npnpm add @integratewise/ui-client\npnpm add @integratewise/capability-client\npnpm add @integratewise/spine-client\n```\n\n---\n\n## Canonical Spine Specification\n\nThe Spine is the **Adaptive Spine Registry** — the authoritative source of truth for all operational metadata.\n\n### Spine v1\n\n```\nSpine v1\n├── Entity Model\n├── Relationship Model\n├── Operational Memory\n├── Continuity\n├── Knowledge\n├── Events\n├── Embeddings\n├── Search\n├── Governance\n└── Workbench Definitions\n```\n\n### Storage Model\n\nThe Spine is a logical model with multiple physical storage mechanisms:\n\n```\nLogical Spine Schema\n        │\n        ▼\nStorage Providers\n├── PostgreSQL (structured data)\n├── JSONB (flexible metadata)\n├── Vector (embeddings)\n├── Object Storage (files)\n├── Cache (hot data)\n└── Search Index (full-text)\n```\n\n**Default implementation:**\n\n- PostgreSQL + JSONB\n- pgvector / Cloudflare Vectorize\n- Redis Cache\n- R2 Object Storage\n\n### Entity Model\n\nEvery canonical entity has:\n\n```\nEntity\n├── Structured (SQL columns)\n├── Flexible (JSONB)\n├── Semantic (Embeddings)\n└── Operational (Timeline, Signals, Evidence)\n```\n\n### Field Semantics\n\nEvery field is a complete operational asset:\n\n```yaml\nentity: Account\n\nfield: account.name\n  storage:\n    type: text\n    column: name\n\n  ui:\n    label: Company Name\n    placeholder: Enter company name\n    control: text\n    required: true\n    section: basic\n\n  search:\n    indexed: true\n    fulltext: true\n\n  embedding:\n    include: true\n\n  permissions:\n    read:\n      - sales\n      - founder\n    write:\n      - sales_manager\n\n  workbenches:\n    founder:\n      visible: true\n      section: overview\n    sales:\n      visible: true\n      section: basic\n    finance:\n      visible: false\n\n  capabilities:\n    requires:\n      - crm.account.create\n      - crm.account.update\n```\n\n### Adaptive UI\n\nThe UI is driven by the Spine, not hardcoded:\n\n```\nWorkbench\n    │\n    ▼\nProjection\n    │\n    ▼\nField Metadata\n    │\n    ▼\nUI Renderer\n```\n\nThe renderer asks: \"How should I display this field?\" not \"Is this the Account Name field?\"\n\n### Adaptive Capabilities\n\nCapabilities declare required fields, not forms:\n\n```yaml\ncapability: crm.account.create\nrequires:\n  - account.name\n  - account.owner\n  - account.industry\n```\n\nThe UI asks: \"What fields does this capability require?\" and renders from Spine schema.\n\n### Workbenches as Projections\n\nInstead of hardcoded workbenches, define role-specific projections:\n\n```yaml\nworkbench: sales\nentities:\n  - account\n  - contact\n  - opportunity\n\ncapabilities:\n  - qualify_lead\n  - create_opportunity\n  - send_email\n\nwidgets:\n  - pipeline\n  - forecast\n  - activities\n```\n\nSame canonical entity, different projection per role.\n\n---\n\n## Role-Specific Workbenches\n\nEvery role gets a projection over the same canonical Spine:\n\n```\nCanonical Spine\n    │\n    ├── Founder Projection\n    ├── Sales Projection\n    ├── Customer Success Projection\n    ├── Marketing Projection\n    ├── Finance Projection\n    ├── Engineering Projection\n    └── Operations Projection\n```\n\nThe underlying entities remain unchanged. Workbenches are views, not separate data models.\n\n---\n\n## Clean State Milestone Priority\n\nIf I had to prioritize, I'd freeze in this order:\n\n1. **Canonical Spine Specification** — entities, relationships, continuity, knowledge, embeddings, workbench definitions\n2. **Capability Model** — what actions exist and how they're governed\n3. **Projection Model** — how workbenches derive views from the Spine\n4. **Protocol Contracts** — UI, Capability, Spine, Event, MCP\n5. **SDKs and packages**\n6. **Service implementations**\n\nThis ensures the platform is driven by stable domain models and contracts, not by current service implementations.\n\n---\n\n## Internal Naming\n\nBecause \"Spine\" has outgrown just \"schema\", consider:\n\n- **Spine Registry** — emphasizes metadata + operational model\n- **Adaptive Spine Registry** — emphasizes adaptation + role-specific projections\n\nThis becomes the authoritative source for:\n\n- Storage semantics\n- UI rendering\n- Validation\n- Permissions\n- Search behavior\n- Embeddings\n- AI context\n- Capability bindings\n- Projection rules\n- Event mappings\n- Synchronization behavior\n\n---\n\n## Summary\n\n| Concept      | Old Thinking      | IntegrateWise Thinking                                 |\n| ------------ | ----------------- | ------------------------------------------------------ |\n| Database     | Schema = tables   | Spine = operational metadata registry                  |\n| API          | Single REST API   | Multiple protocols (UI, Capability, Spine, Event, MCP) |\n| SDK          | One SDK package   | Umbrella + protocol sub-packages                       |\n| UI           | Hardcoded forms   | Adaptive renderer driven by Spine field definitions    |\n| Capabilities | Hardcoded actions | Declarative capability bindings to Spine fields        |\n| Storage      | PostgreSQL tables | Logical Spine + multiple storage providers             |\n| Connectors   | Data importers    | Capability providers behind Connector Runtime          |\n"}