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