{"slug":"architecture/THREE_REPOSITORY_ARCHITECTURE_SPEC","title":"IntegrateWise Three-Repository Architecture Specification","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/THREE_REPOSITORY_ARCHITECTURE_SPEC.mdx","bytes":13786,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Proposed final repository and wiring contract\n**Date:** 31 July 2026\n**Product:** IntegrateWise Spine Workspace\n**Distribution surfaces:** Plugin Marketplace and MCP Marketplace\n**Supersedes:** REPOSITORY_TOPOLOGY_AND_MIGRATION_SPEC.md (D8 two-repo decision)\n\n---\n\n# 1. Architecture Decision\n\nIntegrateWise will operate through exactly three active product repositories:\n\n```text\n1. IntegrateWise Monorepo\n2. Spine Plugin Marketplace\n3. Spine MCP Marketplace\n```\n\nThe split is based on **authority and runtime ownership**, not merely UI packaging.\n\n```text\nIntegrateWise Monorepo\n    owns canonical truth, institutional memory,\n    model infrastructure, platform agents and the full Workbench.\n\nPlugin Marketplace\n    owns Plugin-channel operational state,\n    Plugin sessions, Plugin agent memory and Plugin agents.\n\nMCP Marketplace\n    owns MCP-channel operational state,\n    MCP sessions, MCP agent memory and MCP agents.\n```\n\nBoth channel repositories consume the published IntegrateWise Platform SDK.\n\nThey never access the Canonical Spine, model providers, Governance, Hermes, provider credentials, or Platform databases directly.\n\n---\n\n# 2. Alternatives Considered\n\n## 2.1 Selected: Thin channel repositories\n\n```text\nChannel Repository\n→ Operational Spine\n→ Channel Agent\n→ Platform SDK\n→ Canonical Platform\n```\n\nAdvantages:\n\n- One canonical source of truth\n- Independent marketplace releases\n- Independent channel operational state\n- No duplicated Governance or model routing\n- Clear tenant and profile isolation\n- Easier detection of unmapped paths\n- Plugin and MCP runtimes can evolve independently\n- Canonical business behavior remains consistent\n\nThis is the selected architecture.\n\n## 2.2 Rejected: Three independent platforms\n\nUnder this model, Plugin and MCP repositories would each duplicate:\n\n- Canonical entity models\n- Projection Engine\n- Model routing\n- Governance\n- Hermes\n- Institutional memory\n- Connector logic\n\nThis would create three versions of truth and three execution systems.\n\nRejected.\n\n## 2.3 Rejected: One repository containing all channels\n\nA single repository would reduce packaging overhead, but would couple:\n\n- Browser releases\n- Plugin marketplace review\n- MCP publication\n- Host SDK changes\n- Operational schema migrations\n- Channel-specific incidents\n\nThis would prevent channel-level release and security isolation.\n\nRejected.\n\n---\n\n# 3. Canonical Repository Names\n\n## Repository 1\n\n```text\nintegratewise/integratewise\n```\n\nCanonical logical name:\n\n```text\nIntegrateWise Monorepo\n```\n\nMigration source:\n\n```text\nintegratewise/integratewise-live\n```\n\n## Repository 2\n\n```text\nintegratewise/spine-plugin-marketplace\n```\n\nCanonical logical name:\n\n```text\nSpine Plugin Marketplace\n```\n\nPublished artifact:\n\n```text\nIW-Spine-Network Plugin\n```\n\n## Repository 3\n\n```text\nintegratewise/spine-mcp-marketplace\n```\n\nCanonical logical name:\n\n```text\nSpine MCP Marketplace\n```\n\nPublished artifact:\n\n```text\nIW-Spine-Network MCP\n```\n\n---\n\n# 4. Repository 1 — IntegrateWise Monorepo\n\n## 4.1 Purpose\n\nThe Monorepo is the only repository allowed to own:\n\n- Canonical business truth\n- Canonical institutional memory\n- Platform identity and tenant authority\n- Models and model providers\n- Canonical platform agents\n- Governance\n- Capability resolution\n- Hermes execution\n- Projection generation\n- Full browser Workbench\n- Public Platform SDK contracts\n\n## 4.2 User-facing applications\n\n```text\napps/\n├── marketing\n├── workbench\n├── documentation\n├── changelog\n├── portfolio\n└── platform-admin\n```\n\n## 4.3 Platform services\n\n```text\nservices/\n├── gateway\n├── identity\n├── tenant-authority\n├── configuration-manager\n├── integration-manager\n├── loader\n├── normalizer\n├── triage\n├── canonical-spine\n├── knowledge\n├── institutional-memory\n├── projection-engine\n├── model-gateway\n├── omni-router\n├── agent-runtime\n├── capability-fabric\n├── governance\n├── hermes\n├── reconciliation\n├── billing\n├── observability\n└── audit\n```\n\n## 4.4 Platform packages\n\n```text\npackages/\n├── contracts\n├── schemas\n├── platform-sdk\n├── platform-agent-sdk\n├── react-sdk\n├── projection-contracts\n├── agent-contracts\n├── memory-contracts\n├── tunnel-contracts\n├── governance-contracts\n├── capability-contracts\n├── telemetry\n├── testing\n└── profile-config\n```\n\n## 4.5 Canonical storage\n\nV0 physical ownership:\n\n```text\nD1        Canonical entities, relationships, events and governed memory metadata\nR2        Evidence bytes, documents, files and large artifacts\nVectorize Derived semantic retrieval index\nKV        Hot configuration and replaceable caches\nQueues    Outbox delivery, retries and asynchronous work\nDO        Execution coordination and bounded runtime state\n```\n\n---\n\n# 5. Repository 2 — Spine Plugin Marketplace\n\n## 5.1 Purpose\n\nThe Plugin repository owns the complete Plugin-channel product:\n\n- Plugin marketplace listing\n- Plugin installation\n- Host OAuth handoff\n- Host workspace binding\n- Embedded Plugin UI\n- Plugin skills\n- Plugin templates\n- Host capability discovery\n- Plugin session management\n- Plugin channel agents\n- Plugin agent working memory\n- Plugin operational database\n- Plugin publication and review assets\n\n## 5.2 Plugin operational database\n\nRecommended profile bindings:\n\n```text\niw-plugin-op-dev\niw-plugin-op-customer-zero\niw-plugin-op-external\n```\n\n---\n\n# 6. Repository 3 — Spine MCP Marketplace\n\n## 6.1 Purpose\n\nThe MCP repository owns:\n\n- MCP marketplace listing\n- Remote MCP server\n- MCP transports\n- OAuth and MCP client binding\n- The public IW Spine Tools adapter\n- MCP App UI resources\n- Text and JSON fallback rendering\n- MCP sessions\n- MCP channel agents\n- MCP agent working memory\n- MCP operational database\n- MCP registry publication\n- MCP compatibility testing\n\n## 6.2 MCP operational database\n\nRecommended profile bindings:\n\n```text\niw-mcp-op-dev\niw-mcp-op-customer-zero\niw-mcp-op-external\n```\n\n## 6.3 Public tool contract\n\nThe public inventory remains exactly 19 semantic tools:\n\n1. `get_my_continuity`\n2. `get_active_context`\n3. `get_my_focus`\n4. `get_context`\n5. `get_changes`\n6. `get_related`\n7. `get_history`\n8. `get_commitments`\n9. `get_decisions`\n10. `get_permitted_memory`\n11. `get_relevant_knowledge`\n12. `ask_twin`\n13. `assign_twin`\n14. `get_prepared_work`\n15. `get_available_actions`\n16. `prepare_action`\n17. `get_action_plan`\n18. `approve_action`\n19. `store_in_spine`\n\n---\n\n# 7. Cross-Repository Ownership Matrix\n\n| Responsibility           | Monorepo              | Plugin repo         | MCP repo            |\n| ------------------------ | --------------------- | ------------------- | ------------------- |\n| Canonical DB             | Own                   | Forbidden           | Forbidden           |\n| Canonical entity schema  | Own                   | Consume             | Consume             |\n| Institutional memory     | Own                   | Propose promotion   | Propose promotion   |\n| Model provider registry  | Own                   | Forbidden           | Forbidden           |\n| **Model Gateway**        | **Own**               | **Forbidden**       | **Forbidden**       |\n| **Omni Router**          | **Own**               | **Forbidden**       | **Forbidden**       |\n| Projection Engine        | Own                   | Consume             | Consume             |\n| Platform SDK             | Publish               | Consume             | Consume             |\n| Authentication authority | Own                   | Handoff and session | Handoff and session |\n| Governance               | Own                   | Submit and display  | Submit and display  |\n| Hermes                   | Own                   | Observe only        | Observe only        |\n| Channel agents           | Shared interfaces     | Own Plugin agents   | Own MCP agents      |\n| Channel agent memory     | —                     | Own                 | Own                 |\n| Operational DB           | Platform runtime only | Own Plugin DB       | Own MCP DB          |\n\n---\n\n# 8. The Spine Tunnel\n\n## 8.1 Definition\n\nThe **Spine Tunnel** is the only supported communication boundary between a channel Operational Spine and the Canonical Spine.\n\n```text\nPlugin Operational Spine ─┐\n                          ├── Platform SDK / Spine Tunnel ── Canonical Platform\nMCP Operational Spine ────┘\n```\n\n## 8.2 Tunnel lanes\n\n1. **Projection lane**: Canonical → Channel (projections, context, entities)\n2. **Command lane**: Channel → Canonical (store, propose, approve)\n3. **Observation lane**: Channel → Triage (feedback, patterns, evidence)\n4. **Memory-promotion lane**: Channel memory → Canonical memory\n5. **Execution-status lane**: Governance → Hermes → Provider → Channel\n6. **Reconciliation lane**: Bidirectional checkpoint sync\n\n---\n\n# 9. Three Profiles in Every Repository\n\n```text\ndevelopment\ncustomer-zero\nexternal\n```\n\nProfiles are deployment and isolation contracts, not UI personas.\n\n---\n\n# 10. Three State Classes\n\n| Class                       | Authority              | Examples                                       |\n| --------------------------- | ---------------------- | ---------------------------------------------- |\n| **Client state**            | Browser/host           | Open tab, draft, filters                       |\n| **Operational Spine state** | Channel operational DB | Installation, session, tool call, widget state |\n| **Canonical Spine state**   | Monorepo               | Account, decision, memory, proposal, approval  |\n\n---\n\n# 11. CI Architecture Gates\n\nCI must fail when:\n\n1. Frontend network call not declared in `wiring.yaml`\n2. Channel repo contains canonical DB URL\n3. Channel repo imports internal Platform service\n4. Channel repo imports provider execution SDK\n5. Surface has no declared final-state authority\n6. Operational table lacks owner, retention, tenant key or profile\n7. Agent lacks declared memory scope\n8. Tool lacks Platform SDK mapping\n9. SDK method lacks contract version\n10. Command lacks idempotency key\n11. Profile reuses another profile's resource binding\n12. Customer Zero contains approval bypass\n13. Canonical mutation bypasses governed writers\n14. Direct DB read exists in frontend code\n15. Execution path does not terminate in reconciliation\n16. Endpoint has no active consumer and is not marked internal\n17. Frontend section has no test evidence\n18. Deprecated route remains reachable\n19. Projection cache presented as current without version/freshness\n20. Plugin and MCP contract versions incompatible with deployed Platform SDK\n\n---\n\n# 12. Migration Sequence\n\n## Phase 1 — Freeze ownership\n\n## Phase 2 — Publish Platform contracts\n\n## Phase 3 — Establish central canonical ownership\n\n## Phase 4 — Create Plugin repository\n\n## Phase 5 — Create MCP repository\n\n## Phase 6 — Rebuild Workbench consumers\n\n## Phase 7 — Close all gaps\n\n## Phase 8 — External publication\n\n---\n\n# 13. Final Architecture\n\n```text\n┌─────────────────────────────────────────────────────────────┐\n│ REPOSITORY 1 — INTEGRATEWISE MONOREPO                       │\n│                                                             │\n│ Marketing · Workbench · Docs · Changelog · Portfolio       │\n│                                                             │\n│ Canonical DB · Memory · Knowledge · Models · Providers     │\n│ Canonical Agents · Projection · Governance · Hermes        │\n│ Platform SDK · Agent SDK · Tunnel Contracts                │\n└──────────────────────────────┬──────────────────────────────┘\n                               │\n                  Versioned Platform SDK / Spine Tunnel\n                 ┌─────────────┴──────────────┐\n                 │                            │\n┌────────────────▼────────────────┐  ┌────────▼─────────────────┐\n│ REPOSITORY 2                    │  │ REPOSITORY 3             │\n│ SPINE PLUGIN MARKETPLACE        │  │ SPINE MCP MARKETPLACE    │\n│                                 │  │                          │\n│ Plugin UI                       │  │ Remote MCP               │\n│ Plugin Operational DB           │  │ MCP Operational DB       │\n│ Plugin Sessions                 │  │ MCP Sessions             │\n│ Plugin Agent Memory             │  │ MCP Agent Memory         │\n│ Plugin Channel Agents           │  │ MCP Channel Agents       │\n│ Host Adapters                    │  │ Transport Adapters       │\n│ Plugin Tunnel Worker            │  │ MCP Tunnel Worker        │\n└─────────────────────────────────┘  └──────────────────────────┘\n```\n\n## Final authority rule\n\n```text\nThe Monorepo owns what the organization knows and authorizes.\n\nThe Plugin repository owns how the Plugin channel operates.\n\nThe MCP repository owns how the MCP channel operates.\n\nThe Spine Tunnel is the only route between channel operations\nand canonical organizational continuity.\n```\n"}