Unclassified

IntegrateWise Three-Repository Architecture Specification

Status: Proposed final repository and wiring contract
Date: 31 July 2026
Product: IntegrateWise Spine Workspace
Distribution surfaces: Plugin Marketplace and MCP Marketplace
Supersedes: REPOSITORY_TOPOLOGY_AND_MIGRATION_SPEC.md (D8 two-repo decision)

1. Architecture Decision

IntegrateWise will operate through exactly three active product repositories:

1. IntegrateWise Monorepo
2. Spine Plugin Marketplace
3. Spine MCP Marketplace

The split is based on authority and runtime ownership, not merely UI packaging.

IntegrateWise Monorepo
    owns canonical truth, institutional memory,
    model infrastructure, platform agents and the full Workbench.

Plugin Marketplace
    owns Plugin-channel operational state,
    Plugin sessions, Plugin agent memory and Plugin agents.

MCP Marketplace
    owns MCP-channel operational state,
    MCP sessions, MCP agent memory and MCP agents.

Both channel repositories consume the published IntegrateWise Platform SDK.

They never access the Canonical Spine, model providers, Governance, Hermes, provider credentials, or Platform databases directly.

2. Alternatives Considered

2.1 Selected: Thin channel repositories

Channel Repository
→ Operational Spine
→ Channel Agent
→ Platform SDK
→ Canonical Platform

Advantages:

One canonical source of truth
Independent marketplace releases
Independent channel operational state
No duplicated Governance or model routing
Clear tenant and profile isolation
Easier detection of unmapped paths
Plugin and MCP runtimes can evolve independently
Canonical business behavior remains consistent

This is the selected architecture.

2.2 Rejected: Three independent platforms

Under this model, Plugin and MCP repositories would each duplicate:

Canonical entity models
Projection Engine
Model routing
Governance
Hermes
Institutional memory
Connector logic

This would create three versions of truth and three execution systems.

Rejected.

2.3 Rejected: One repository containing all channels

A single repository would reduce packaging overhead, but would couple:

Browser releases
Plugin marketplace review
MCP publication
Host SDK changes
Operational schema migrations
Channel-specific incidents

This would prevent channel-level release and security isolation.

Rejected.

3. Canonical Repository Names

Repository 1

integratewise/integratewise

Canonical logical name:

IntegrateWise Monorepo

Migration source:

integratewise/integratewise-live

Repository 2

integratewise/spine-plugin-marketplace

Canonical logical name:

Spine Plugin Marketplace

Published artifact:

IW-Spine-Network Plugin

Repository 3

integratewise/spine-mcp-marketplace

Canonical logical name:

Spine MCP Marketplace

Published artifact:

IW-Spine-Network MCP

4. Repository 1 — IntegrateWise Monorepo

4.1 Purpose

The Monorepo is the only repository allowed to own:

Canonical business truth
Canonical institutional memory
Platform identity and tenant authority
Models and model providers
Canonical platform agents
Governance
Capability resolution
Hermes execution
Projection generation
Full browser Workbench
Public Platform SDK contracts

4.2 User-facing applications

apps/
├── marketing
├── workbench
├── documentation
├── changelog
├── portfolio
└── platform-admin

4.3 Platform services

services/
├── gateway
├── identity
├── tenant-authority
├── configuration-manager
├── integration-manager
├── loader
├── normalizer
├── triage
├── canonical-spine
├── knowledge
├── institutional-memory
├── projection-engine
├── model-gateway
├── omni-router
├── agent-runtime
├── capability-fabric
├── governance
├── hermes
├── reconciliation
├── billing
├── observability
└── audit

4.4 Platform packages

packages/
├── contracts
├── schemas
├── platform-sdk
├── platform-agent-sdk
├── react-sdk
├── projection-contracts
├── agent-contracts
├── memory-contracts
├── tunnel-contracts
├── governance-contracts
├── capability-contracts
├── telemetry
├── testing
└── profile-config

4.5 Canonical storage

V0 physical ownership:

D1        Canonical entities, relationships, events and governed memory metadata
R2        Evidence bytes, documents, files and large artifacts
Vectorize Derived semantic retrieval index
KV        Hot configuration and replaceable caches
Queues    Outbox delivery, retries and asynchronous work
DO        Execution coordination and bounded runtime state

5. Repository 2 — Spine Plugin Marketplace

5.1 Purpose

The Plugin repository owns the complete Plugin-channel product:

Plugin marketplace listing
Plugin installation
Host OAuth handoff
Host workspace binding
Embedded Plugin UI
Plugin skills
Plugin templates
Host capability discovery
Plugin session management
Plugin channel agents
Plugin agent working memory
Plugin operational database
Plugin publication and review assets

5.2 Plugin operational database

Recommended profile bindings:

iw-plugin-op-dev
iw-plugin-op-customer-zero
iw-plugin-op-external

6. Repository 3 — Spine MCP Marketplace

6.1 Purpose

The MCP repository owns:

MCP marketplace listing
Remote MCP server
MCP transports
OAuth and MCP client binding
The public IW Spine Tools adapter
MCP App UI resources
Text and JSON fallback rendering
MCP sessions
MCP channel agents
MCP agent working memory
MCP operational database
MCP registry publication
MCP compatibility testing

6.2 MCP operational database

Recommended profile bindings:

iw-mcp-op-dev
iw-mcp-op-customer-zero
iw-mcp-op-external

6.3 Public tool contract

The public inventory remains exactly 19 semantic tools:

get_my_continuity
get_active_context
get_my_focus
get_context
get_changes
get_related
get_history
get_commitments
get_decisions
get_permitted_memory
get_relevant_knowledge
ask_twin
assign_twin
get_prepared_work
get_available_actions
prepare_action
get_action_plan
approve_action
store_in_spine

7. Cross-Repository Ownership Matrix

Responsibility	Monorepo	Plugin repo	MCP repo
Canonical DB	Own	Forbidden	Forbidden
Canonical entity schema	Own	Consume	Consume
Institutional memory	Own	Propose promotion	Propose promotion
Model provider registry	Own	Forbidden	Forbidden
Model Gateway	Own	Forbidden	Forbidden
Omni Router	Own	Forbidden	Forbidden
Projection Engine	Own	Consume	Consume
Platform SDK	Publish	Consume	Consume
Authentication authority	Own	Handoff and session	Handoff and session
Governance	Own	Submit and display	Submit and display
Hermes	Own	Observe only	Observe only
Channel agents	Shared interfaces	Own Plugin agents	Own MCP agents
Channel agent memory	—	Own	Own
Operational DB	Platform runtime only	Own Plugin DB	Own MCP DB

8. The Spine Tunnel

8.1 Definition

The Spine Tunnel is the only supported communication boundary between a channel Operational Spine and the Canonical Spine.

Plugin Operational Spine ─┐
                          ├── Platform SDK / Spine Tunnel ── Canonical Platform
MCP Operational Spine ────┘

8.2 Tunnel lanes

Projection lane: Canonical → Channel (projections, context, entities)
Command lane: Channel → Canonical (store, propose, approve)
Observation lane: Channel → Triage (feedback, patterns, evidence)
Memory-promotion lane: Channel memory → Canonical memory
Execution-status lane: Governance → Hermes → Provider → Channel
Reconciliation lane: Bidirectional checkpoint sync

9. Three Profiles in Every Repository

development
customer-zero
external

Profiles are deployment and isolation contracts, not UI personas.

10. Three State Classes

Class	Authority	Examples
Client state	Browser/host	Open tab, draft, filters
Operational Spine state	Channel operational DB	Installation, session, tool call, widget state
Canonical Spine state	Monorepo	Account, decision, memory, proposal, approval

11. CI Architecture Gates

CI must fail when:

Frontend network call not declared in wiring.yaml
Channel repo contains canonical DB URL
Channel repo imports internal Platform service
Channel repo imports provider execution SDK
Surface has no declared final-state authority
Operational table lacks owner, retention, tenant key or profile
Agent lacks declared memory scope
Tool lacks Platform SDK mapping
SDK method lacks contract version
Command lacks idempotency key
Profile reuses another profile's resource binding
Customer Zero contains approval bypass
Canonical mutation bypasses governed writers
Direct DB read exists in frontend code
Execution path does not terminate in reconciliation
Endpoint has no active consumer and is not marked internal
Frontend section has no test evidence
Deprecated route remains reachable
Projection cache presented as current without version/freshness
Plugin and MCP contract versions incompatible with deployed Platform SDK

12. Migration Sequence

Phase 1 — Freeze ownership

Phase 2 — Publish Platform contracts

Phase 3 — Establish central canonical ownership

Phase 4 — Create Plugin repository

Phase 5 — Create MCP repository

Phase 6 — Rebuild Workbench consumers

Phase 7 — Close all gaps

Phase 8 — External publication

13. Final Architecture

┌─────────────────────────────────────────────────────────────┐
│ REPOSITORY 1 — INTEGRATEWISE MONOREPO                       │
│                                                             │
│ Marketing · Workbench · Docs · Changelog · Portfolio       │
│                                                             │
│ Canonical DB · Memory · Knowledge · Models · Providers     │
│ Canonical Agents · Projection · Governance · Hermes        │
│ Platform SDK · Agent SDK · Tunnel Contracts                │
└──────────────────────────────┬──────────────────────────────┘
                               │
                  Versioned Platform SDK / Spine Tunnel
                 ┌─────────────┴──────────────┐
                 │                            │
┌────────────────▼────────────────┐  ┌────────▼─────────────────┐
│ REPOSITORY 2                    │  │ REPOSITORY 3             │
│ SPINE PLUGIN MARKETPLACE        │  │ SPINE MCP MARKETPLACE    │
│                                 │  │                          │
│ Plugin UI                       │  │ Remote MCP               │
│ Plugin Operational DB           │  │ MCP Operational DB       │
│ Plugin Sessions                 │  │ MCP Sessions             │
│ Plugin Agent Memory             │  │ MCP Agent Memory         │
│ Plugin Channel Agents           │  │ MCP Channel Agents       │
│ Host Adapters                    │  │ Transport Adapters       │
│ Plugin Tunnel Worker            │  │ MCP Tunnel Worker        │
└─────────────────────────────────┘  └──────────────────────────┘

Final authority rule

The Monorepo owns what the organization knows and authorizes.

The Plugin repository owns how the Plugin channel operates.

The MCP repository owns how the MCP channel operates.

The Spine Tunnel is the only route between channel operations
and canonical organizational continuity.