Superseded
IntegrateWise Complete Flow Architecture
Date: 2026-07-31
Status: SUPERSEDED — absorbed into INTEGRATEWISE_ARCHITECTURE.md v2.2. Historical reference only.
Supersedes: Previous ad-hoc routing and binding decisions
1. Architecture Overview
The IntegrateWise platform follows a three-manager architecture with a cascade discovery model for external users.
┌─────────────────────────────────────────────────────────────────────┐
│ PRODUCT EXPERIENCE │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │
│ │ Workbench │ │ Connector │ │ Twin UX │ │ Approval │ │
│ │ (Full UI) │ │ Tray │ │ │ │ UX │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └─────┬─────┘ │
│ │ │ │ │ │
└─────────┼────────────────┼────────────────┼────────────────┼────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ CLOUDFLARE GATEWAY │
│ │
│ Authentication → TenantGate → Policy Edge → Rate Limit → Routing │
│ │
└──────────────────────────────┬──────────────────────────────────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ INTEGRATION │ │ CONFIGURATION │ │ ACTIVATION │
│ MANAGER │ │ MANAGER │ │ MANAGER │
│ │ │ │ │ │
│ What tools │ │ How to configure│ │ Is it ready │
│ are available? │ │ and activate? │ │ to use? │
│ │ │ │ │ │
│ • Discover │ │ • Tool configs │ │ • State machine │
│ • Explore │ │ • Credentials │ │ • Consent │
│ • Connect │ │ • Parameters │ │ • Binding │
│ • Import │ │ • Validation │ │ • Hydration │
│ • Schema │ │ • Spine Tunnel │ │ • Activation │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
└────────────────────┼────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ ROUTER LOGIC │
│ │
│ Routes requests to the correct manager based on: │
│ • Operation type (discover/configure/activate) │
│ • Entity type (connector/tool/schema) │
│ • Tenant context (industry/needs/goals) │
│ │
└──────────────────────────────┬──────────────────────────────────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ SCHEMA AI │ │ INTELLIGENCE │ │ KNOWLEDGE │
│ GENERATOR │ │ (Twin) │ │ │
│ │ │ │ │ │
│ Dynamic schema │ │ Context assembly│ │ Evidence │
│ generation │ │ Reasoning │ │ Memory │
│ Multi-agent │ │ Proposals │ │ Learning │
│ Industry-aware │ │ Monitoring │ │ Synthesis │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
└────────────────────┼────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ SPINE TUNNEL │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Projection Lane │ │ Command Lane │ │ Observation Lane│ │
│ │ Canonical → Ch │ │ Ch → Canonical │ │ Ch → Triage │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Memory Lane │ │ Execution Lane │ │ Reconciliation │ │
│ │ Ch → Canonical │ │ Gov → Provider │ │ Bidirectional │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
└──────────────────────────────┬──────────────────────────────────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ OPERATIONAL │ │ CANONICAL │ │ CHANNEL │
│ SPINE (D1) │ │ SPINE (D1) │ │ OPERATIONAL DB │
│ │ │ │ │ │
│ Channel state │ │ Business truth │ │ Plugin/MCP │
│ Sessions │ │ Entities │ │ sessions │
│ Tool calls │ │ Relationships │ │ Agent memory │
│ Projections │ │ Memory │ │ Tool calls │
│ Sync checkpoints│ │ Audit │ │ Projections │
└─────────────────┘ └─────────────────┘ └─────────────────┘
2. Three Manager Responsibilities
2.1 Integration Manager
Question it answers: "What tools are available?"
| Responsibility | Description |
|---|---|
| Discovery | Find all tools connected to the host platform |
| Exploration | Examine capabilities, schemas, health of each tool |
| Connection | Establish tunnel to each discovered tool |
| Import | Bring discovered tools into the Spine Network |
| Schema | Pass raw schemas to Schema AI Generator |
Service: integration-management-mcp
API Endpoints:
POST /discover— Discover tools from host platformGET /tools— List all discovered toolsGET /tools/:id— Get tool detailsPOST /tools/:id/connect— Establish connectionGET /tools/:id/health— Check tool health
2.2 Configuration Manager
Question it answers: "How is this tool configured and activated?"
| Responsibility | Description |
|---|---|
| Tool Configuration | Store and manage tool configurations |
| Credential Management | Handle API keys, tokens, secrets |
| Parameter Validation | Validate configuration before activation |
| Spine Tunnel | Expose the tunnel boundary |
| Activation | Activate tools based on configuration |
Service: provider-management-mcp (expanded)
API Endpoints:
POST /configure— Configure a toolGET /configurations— List all configurationsGET /configurations/:id— Get configuration detailsPUT /configurations/:id— Update configurationPOST /configurations/:id/activate— Activate toolGET /tunnel/status— Check tunnel status
2.3 Activation Manager
Question it answers: "Is this tool ready to use?"
| Responsibility | Description |
|---|---|
| State Machine | Govern activation lifecycle |
| Consent | Handle user consent |
| Binding | Bind tool to tenant |
| Hydration | Hydrate initial data |
| Activation | Mark tool as active |
Service: marketplace-installation
State Machine:
initiated → identity_required → workspace_required → consent_required
→ binding → hydrating → active
API Endpoints:
POST /installations— Start installationPOST /installations/:id/identity— Provide identityPOST /installations/:id/workspace— Select workspacePOST /installations/:id/consent— Provide consentPOST /installations/:id/activate— ActivateGET /installations/:id— Get installation status
3. Cascade Discovery Flow (External Users)
3.1 Plugin Marketplace Activation
User clicks Plugin marketplace tool
↓
Host platform (ChatGPT) is first entry point
↓
Integration Manager discovers all apps connected to ChatGPT
↓
For each discovered app:
1. Integration Manager explores capabilities
2. Integration Manager passes schema to Schema AI Generator
3. Schema AI Generator normalizes and adapts schema
4. Configuration Manager stores configuration
5. Activation Manager governs activation
↓
Connector Tray shows: "Here's everything we found"
↓
User manages all tools from one surface
3.2 MCP Marketplace Activation
User clicks MCP marketplace tool
↓
Host platform (Claude) is first entry point
↓
Integration Manager discovers all tools connected to Claude
↓
Same cascade as Plugin Marketplace
↓
All discovered tools come under Spine management
3.3 Direct Activation (Customer Zero / Development)
Admin configures tool directly
↓
Configuration Manager stores configuration
↓
Activation Manager governs activation
↓
Tool is immediately available
4. Schema AI Generator Flow
4.1 Input
Raw Connector Schema (OpenAPI, GraphQL, JSON Schema, Raw Objects)
↓
Tenant Context (industry, needs, goals, milestones)
↓
Schema AI Generator
4.2 Processing
1. Normalize raw schema → canonical entity types
2. Adapt based on tenant context:
- Industry-specific lifecycle events
- Goal-driven automations
- Milestone tracking
- Needs-based prioritization
3. Generate tenant-specific schema
4. Multi-agent validation and refinement
4.3 Output
Adapted Schema:
├── Entity types (with lifecycle events)
├── Capabilities (with policies)
├── Lifecycle events (industry + goal + milestone)
└── Confidence scores
5. Spine Tunnel Flow
5.1 Projection Lane
Canonical Spine → Projection Engine → Platform SDK → Channel Projection Cache → Frontend
5.2 Command Lane
Frontend → Channel Command Outbox → Platform SDK → Gateway → Service → Governed Writer → Canonical Spine
5.3 Observation Lane
Channel Interaction → Operational Observation → Platform SDK → Triage → Learning Evidence
5.4 Memory Promotion Lane
Channel Agent Memory → Promotion Proposal → Evidence Validation → Governance → Canonical Memory
5.5 Execution Status Lane
Governance → Hermes → Provider → Outcome → Canonical Spine → Execution Projection → Channel → Frontend
5.6 Reconciliation Lane
Operational Checkpoint ↔ Platform Checkpoint
6. Service Bindings (Gateway → Services)
6.1 Core Services
| Binding | Service | Responsibility |
|---|---|---|
INTEGRATION_MCP | integration-management-mcp | Tool discovery and exploration |
PROVIDER_MCP | provider-management-mcp | Configuration management |
MARKETPLACE_INSTALLATION | marketplace-installation | Activation management |
SCHEMA_AI | schema-ai | Dynamic schema generation |
INTELLIGENCE | intelligence | Twin reasoning |
KNOWLEDGE | knowledge | Memory and learning |
PIPELINE | pipeline | Normalization and triage |
CONNECTOR | connector | Provider connections |
MCP_CONNECTOR | mcp-connector | MCP tool contract |
MCP_POOL | mcp-pool | Capability routing |
6.2 Gateway Routes
| Route | Binding | Description |
|---|---|---|
/api/v1/integrations | INTEGRATION_MCP | Tool discovery and exploration |
/api/v1/providers | PROVIDER_MCP | Configuration management |
/api/v1/marketplace/installations | MARKETPLACE_INSTALLATION | Activation management |
/api/v1/schema | SCHEMA_AI | Dynamic schema generation |
/api/v1/cognitive/* | INTELLIGENCE | Twin reasoning |
/api/v1/knowledge | KNOWLEDGE | Memory and learning |
/api/v1/pipeline | PIPELINE | Normalization and triage |
/api/v1/connectors | CONNECTOR | Provider connections |
/api/v1/spine-network | MCP_CONNECTOR | MCP tool contract |
/api/v1/mcp-pool | MCP_POOL | Capability routing |
7. Frontend → Backend → AI Flow
7.1 Connector Tray Flow
Frontend: Connector Tray component
↓
Gateway: /api/v1/integrations/tools
↓
Integration Manager: List discovered tools
↓
Gateway: /api/v1/schema/:tenant
↓
Schema AI: Get registered schemas for tenant
↓
Frontend: Render tool list with schemas
7.2 Tool Configuration Flow
Frontend: Tool configuration form
↓
Gateway: /api/v1/providers/configure
↓
Configuration Manager: Store configuration
↓
Gateway: /api/v1/marketplace/installations
↓
Activation Manager: Start activation
↓
Frontend: Show activation progress
7.3 Twin Interaction Flow
Frontend: Ask Twin
↓
Gateway: /api/v1/cognitive/think
↓
Intelligence: Assemble context, reason
↓
Gateway: /api/v1/schema/generate
↓
Schema AI: Generate tenant-specific schema
↓
Intelligence: Prepare proposal
↓
Frontend: Show proposal
7.4 Execution Flow
Frontend: Approve action
↓
Gateway: /api/v1/governance/decide
↓
Governance: Record approval
↓
Gateway: /api/v1/hermes/execute
↓
Hermes: Coordinate execution
↓
Provider: Execute action
↓
Outcome: Re-ingest and reconcile
↓
Frontend: Show reconciled state
8. Multi-Agent Schema Generation
8.1 Agent Types
| Agent | Role | Input | Output |
|---|---|---|---|
| Normalizer | Transform raw schema | Raw connector schema | Normalized entities |
| Adapter | Adapt for tenant context | Normalized entities + tenant context | Adapted entities |
| Validator | Validate schema quality | Adapted entities | Validation report |
| Composer | Compose final schema | Validated entities | Final schema |
8.2 Multi-Agent Flow
Raw Schema → Normalizer → Adapter → Validator → Composer → Final Schema
↑
│
Tenant Context
(industry, needs, goals, milestones)
9. Configuration Manager as Central Point
The Configuration Manager is the single point of truth for all tool configurations:
┌─────────────────────────────────────────────────────────────┐
│ CONFIGURATION MANAGER │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Tool Configurations │ │
│ │ • API keys, tokens, secrets │ │
│ │ • Connection parameters │ │
│ │ • Sync settings │ │
│ │ • Webhook URLs │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Spine Tunnel Exposure │ │
│ │ • Tunnel endpoints │ │
│ │ • Projection feeds │ │
│ │ • Command routing │ │
│ │ • Observation streams │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Activation Management │ │
│ │ • Configuration validation │ │
│ │ • Pre-activation checks │ │
│ │ • Activation triggers │ │
│ │ • Post-activation verification │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
10. Non-Negotiable Rules
- Configuration Manager is the single point of truth for all tool configurations
- Spine Tunnel is the only route between channel operations and canonical truth
- Cascade discovery — one host connection discovers ALL connected tools
- Schema AI Generator adapts based on tenant context (industry, needs, goals, milestones)
- No forced adoption — users pick from Connector Tray
- Three managers handle distinct responsibilities (integration, configuration, activation)
- Router logic routes based on operation type, not URL prefix
- Multi-agent validation ensures schema quality
- Lifecycle events are tenant-scoped and industry-aware
- External success is not canonical success until observed and reconciled