Unclassified

IntegrateWise Platform Architecture — Multi-Protocol Platform

This document defines the canonical architecture for IntegrateWise as a multi-protocol platform.

Core Principle

IntegrateWise is not a single REST or GraphQL API. It is a multi-protocol platform.

                    IntegrateWise
                ┌──────────────────┐
                │ UI Protocol      │
                ├──────────────────┤
                │ Capability       │
                ├──────────────────┤
                │ Spine Network    │
                ├──────────────────┤
                │ Events           │
                ├──────────────────┤
                │ MCP              │
                └──────────────────┘

Each protocol has distinct responsibilities and consumers.

The Three Protocols

1. UI Protocol

Purpose: Read-heavy, UI-oriented interactions for applications like Customer Zero.

Consumers:

Customer Zero web app
Marketplace
Admin dashboard
Mobile apps

Example methods:

workbench.get();
entity360.get();
search.query();
notifications.list();
timeline.get();
projection.get();

Characteristics:

Session-oriented
Read-heavy
Projection-driven
UI-optimized response shapes

2. Capability Protocol

Purpose: Governed execution of business actions.

Consumers:

Customer Zero
Twin
MCP Pool
CLI tools
Automation workflows

Example methods:

capability.execute({
  capability: "crm.account.create",
  params: { name: "Acme Corp" },
});

capability.invoke();
capability.describe();
registry.find("crm.account.create");

Characteristics:

Execution-oriented
Governed by policies
Two-gate approval
Event-producing
NOT for reading data

3. Spine Network Protocol

Purpose: Canonical operational memory and continuity.

Consumers:

Projection Engine
Capability Engine
Connector Runtime
Schema AI
MCP Pool
Entity360

Example methods:

spine.resolveEntity(id);
spine.subscribe(entityId);
spine.continuity(sessionId);
spine.remember(memory);
spine.context(tenantId);
spine.observe(query);
spine.link(sourceId, targetId, relation);
spine.promote(entityId);

Characteristics:

Memory-oriented
Subscription-based
Continuity-first
NOT a CRUD API
NOT a UI API
NOT a capability execution API

Protocol Boundaries

Customer Zero
    │
    ├── UI Client ──────────────┐
    │                          │
    ├── Capability Client ─────┤
    │                          │
    └── Spine Client ──────────┘
                              │
                              ▼
                        Gateway
                              │
              ┌───────────────┼───────────────┐
              │               │               │
         UI Service    Capability Service  Spine Service
              │               │               │
              └───────────────┼───────────────┘
                              │
                        Adaptive Spine

Rule: No protocol bypasses its designated service. The UI client never directly executes capabilities. The capability client never directly reads workbench projections.

SDK Structure

Instead of one monolithic SDK, split by protocol:

@integratewise/sdk                    ← umbrella/primary package
@integratewise/ui-client              ← UI Protocol
@integratewise/capability-client      ← Capability Protocol
@integratewise/spine-client           ← Spine Network Protocol

Primary Entry Point

Most developers install one package:

pnpm add @integratewise/sdk


const platform = createPlatformClient({
  endpoint: "https://gateway.dev.integratewise.ai",
  token: INTEGRATEWISE_API_TOKEN,
  tenantId: INTEGRATEWISE_TENANT_ID,
});

// UI Protocol
const workbench = await platform.ui.workbench.get("SALES");
const searchResults = await platform.ui.search.query({ q: "Acme" });

// Capability Protocol
const result = await platform.capabilities.execute({
  capability: "crm.account.create",
  params: { name: "Acme Corp" },
});

// Spine Protocol
const entity = await platform.spine.resolveEntity("acc_123");
await platform.spine.remember({ type: "semantic", content: {...} });

Advanced Usage

Advanced consumers can install sub-packages:

pnpm add @integratewise/ui-client
pnpm add @integratewise/capability-client
pnpm add @integratewise/spine-client

Canonical Spine Specification

The Spine is the Adaptive Spine Registry — the authoritative source of truth for all operational metadata.

Spine v1

Spine v1
├── Entity Model
├── Relationship Model
├── Operational Memory
├── Continuity
├── Knowledge
├── Events
├── Embeddings
├── Search
├── Governance
└── Workbench Definitions

Storage Model

The Spine is a logical model with multiple physical storage mechanisms:

Logical Spine Schema
        │
        ▼
Storage Providers
├── PostgreSQL (structured data)
├── JSONB (flexible metadata)
├── Vector (embeddings)
├── Object Storage (files)
├── Cache (hot data)
└── Search Index (full-text)

Default implementation:

PostgreSQL + JSONB
pgvector / Cloudflare Vectorize
Redis Cache
R2 Object Storage

Entity Model

Every canonical entity has:

Entity
├── Structured (SQL columns)
├── Flexible (JSONB)
├── Semantic (Embeddings)
└── Operational (Timeline, Signals, Evidence)

Field Semantics

Every field is a complete operational asset:

entity: Account

field: account.name
  storage:
    type: text
    column: name

  ui:
    label: Company Name
    placeholder: Enter company name
    control: text
    required: true
    section: basic

  search:
    indexed: true
    fulltext: true

  embedding:
    include: true

  permissions:
    read:
      - sales
      - founder
    write:
      - sales_manager

  workbenches:
    founder:
      visible: true
      section: overview
    sales:
      visible: true
      section: basic
    finance:
      visible: false

  capabilities:
    requires:
      - crm.account.create
      - crm.account.update

Adaptive UI

The UI is driven by the Spine, not hardcoded:

Workbench
    │
    ▼
Projection
    │
    ▼
Field Metadata
    │
    ▼
UI Renderer

The renderer asks: "How should I display this field?" not "Is this the Account Name field?"

Adaptive Capabilities

Capabilities declare required fields, not forms:

capability: crm.account.create
requires:
  - account.name
  - account.owner
  - account.industry

The UI asks: "What fields does this capability require?" and renders from Spine schema.

Workbenches as Projections

Instead of hardcoded workbenches, define role-specific projections:

workbench: sales
entities:
  - account
  - contact
  - opportunity

capabilities:
  - qualify_lead
  - create_opportunity
  - send_email

widgets:
  - pipeline
  - forecast
  - activities

Same canonical entity, different projection per role.

Role-Specific Workbenches

Every role gets a projection over the same canonical Spine:

Canonical Spine
    │
    ├── Founder Projection
    ├── Sales Projection
    ├── Customer Success Projection
    ├── Marketing Projection
    ├── Finance Projection
    ├── Engineering Projection
    └── Operations Projection

The underlying entities remain unchanged. Workbenches are views, not separate data models.

Clean State Milestone Priority

If I had to prioritize, I'd freeze in this order:

Canonical Spine Specification — entities, relationships, continuity, knowledge, embeddings, workbench definitions
Capability Model — what actions exist and how they're governed
Projection Model — how workbenches derive views from the Spine
Protocol Contracts — UI, Capability, Spine, Event, MCP
SDKs and packages
Service implementations

This ensures the platform is driven by stable domain models and contracts, not by current service implementations.

Internal Naming

Because "Spine" has outgrown just "schema", consider:

Spine Registry — emphasizes metadata + operational model
Adaptive Spine Registry — emphasizes adaptation + role-specific projections

This becomes the authoritative source for:

Storage semantics
UI rendering
Validation
Permissions
Search behavior
Embeddings
AI context
Capability bindings
Projection rules
Event mappings
Synchronization behavior

Summary

Concept	Old Thinking	IntegrateWise Thinking
Database	Schema = tables	Spine = operational metadata registry
API	Single REST API	Multiple protocols (UI, Capability, Spine, Event, MCP)
SDK	One SDK package	Umbrella + protocol sub-packages
UI	Hardcoded forms	Adaptive renderer driven by Spine field definitions
Capabilities	Hardcoded actions	Declarative capability bindings to Spine fields
Storage	PostgreSQL tables	Logical Spine + multiple storage providers
Connectors	Data importers	Capability providers behind Connector Runtime