{"slug":"architecture/v2-ai-capability-fabric","title":"IntegrateWise AI Capability Fabric","section":"architecture","sectionLabel":"Architecture","status":"current","type":"document","path":"architecture/v2-ai-capability-fabric.mdx","bytes":18309,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** FROZEN — Final Platform Boundary  \n**Domain:** AI substrate, provider independence, model routing, capability contracts  \n**Date:** 2026-07-12  \n**Version:** 1.0.0-CANONICAL  \n**Supersedes:** `docs/architecture/v2-provider-fabric.md` §AI surface; prior provider/routing drafts  \n**Authority:** Founder / Platform Doctrine\n\n**Canonical Reference:** [CANONICAL_PLATFORM_ARCHITECTURE.md](./CANONICAL_PLATFORM_ARCHITECTURE.md)\n\n> This document is downstream of the Canonical Platform Architecture. When this document contradicts the canonical architecture, the canonical architecture wins.\n\n---\n\n## 1. Architecture Law\n\n> **No external provider owns an IntegrateWise architectural boundary.**\n\nThat applies to AI and every other provider plane:\n\n```text\nAuth / Database / Spine / Cache / Queue / Storage / Vector / Search\nAI provider / Model / AI gateway / Embedding / Reranking / Inference\nAgent runtime / Tool runtime / MCP runtime\nConnector provider / OAuth broker\nObservability / Analytics / Billing / Mail / Secrets / Feature flags\n```\n\nLaw:\n\n```text\nIntegrateWise defines capability contracts\n      ↓\nPlatform resolves configured implementations\n      ↓\nProviders execute them\n```\n\nSpecifically for AI:\n\n> **Twin asks for intelligence.  \n> Hermes determines execution.  \n> Governance determines permission.  \n> The router determines capability/model.  \n> The gateway determines transport.  \n> The provider performs inference.  \n> No model owns truth or workflow state.**\n\nThis is the **Provider Independence Law**.\n\n---\n\n## 2. AI Is a Capability Fabric\n\nProduct/Workbench/Twin must never target a vendor, model, or gateway in architecture or contract shape.\n\n```text\nProduct / Workbench / Twin\n            │\n            ▼\n       AI Capability SDK\n            │\n            ▼\n      AI Runtime / Hermes\n            │\n   ┌────────┼───────────┐\n   ▼        ▼           ▼\nGateway   Router     Governance\n   │        │           │\n   ▼        ▼           ▼\nProvider  Model      Policy /\nAdapter   Resolver   Approval\n   │\n   ▼\nExternal AI Substrate\n```\n\nProduct code only sees capability contracts and intents.\n\n---\n\n## 3. Contract Surfaces\n\n```text\nAIProvider\nModelProvider\nAIGateway\nModelRouter\nEmbeddingProvider\nRerankProvider\nInferenceProvider\nAgentRuntime\nToolRuntime\nMemoryProvider\nPromptRegistry\nContextProvider\nGuardrailProvider\nEvaluationProvider\nObservabilityProvider\n```\n\n---\n\n## 4. AIProvider\n\nRepresents the external AI vendor/API substrate.\n\n```ts\ninterface AIProvider {\n  id: string;\n\n  generate(request: GenerationRequest): Promise<GenerationResult>;\n\n  stream(request: GenerationRequest): AsyncIterable<GenerationChunk>;\n\n  capabilities(): Promise<ProviderCapabilities>;\n}\n```\n\nAdapters are implementation details only:\n\n```text\nOpenAIProvider\nAnthropicProvider\nGoogleProvider\nOpenRouterProvider\nAzureOpenAIProvider\nBedrockProvider\nCloudflareAIProvider\nLocalInferenceProvider\n```\n\nProviders may target OpenAI, Anthropic, Google AI, OpenRouter, Bedrock, Cloudflare Workers AI, or other substrates. None of these provider names belong in product architecture.\n\n---\n\n## 5. ModelProvider\n\nModel identity/capability metadata is separate from API execution.\n\n```ts\ninterface ModelDescriptor {\n  id: string;\n  provider: string;\n\n  capabilities: {\n    reasoning: boolean;\n    vision: boolean;\n    tools: boolean;\n    structuredOutput: boolean;\n    embeddings: boolean;\n  };\n\n  contextWindow: number;\n\n  economics: {\n    inputCost: number;\n    outputCost: number;\n  };\n\n  governance: {\n    dataResidency?: string[];\n    allowedScopes?: MemoryScope[];\n    sensitivityLevel?: number;\n  };\n}\n```\n\nModel identity examples:\n\n```text\nprovider = anthropic\nmodel    = claude-sonnet-x\n\nprovider = openai\nmodel    = gpt-x\n\nprovider = openrouter\nmodel    = provider/model\n```\n\n**Never use model names as architecture.**\n\nBad:\n\n```ts\ncallClaude();\ncallGPT();\ncallGemini();\n```\n\nCorrect:\n\n```ts\nai.execute({\n  capability: \"reasoning\",\n  task: \"account-risk-analysis\",\n});\n```\n\n---\n\n## 6. AIGateway\n\nThe AI Gateway is an execution transport boundary, not a product boundary.\n\n```ts\ninterface AIGateway {\n  execute(request: AIExecutionRequest): Promise<AIExecutionResult>;\n\n  stream(request: AIExecutionRequest): AsyncIterable<AIExecutionChunk>;\n}\n```\n\nPossible implementations:\n\n```text\nDirectGateway\nCloudflareAIGateway\nOpenRouterGateway\nLiteLLMGateway\nInternalHermesGateway\nEnterpriseProxyGateway\n```\n\nRouting:\n\n```text\nTwin\n │\n ▼\nAI SDK\n │\n ▼\nHermes\n │\n ▼\nAIGateway\n │\n ├── Direct Provider\n ├── Cloudflare AI Gateway\n ├── OpenRouter\n ├── Enterprise AI Proxy\n └── Customer-hosted Gateway\n```\n\nProduct code must not know which gateway implementation is active.\n\n---\n\n## 7. ModelRouter\n\nHermes requests a capability, not a model.\n\n```ts\ninterface ModelRouter {\n  resolve(intent: AIIntent, context: ExecutionContext): Promise<ModelRoute>;\n}\n```\n\nExample:\n\n```ts\nawait ai.execute({\n  intent: \"summarize_customer_history\",\n  requirements: {\n    latency: \"interactive\"\n    sensitivity: \"internal\"\n    reasoning: \"medium\"\n    structuredOutput: true\n  }\n})\n```\n\nResolution order:\n\n```text\nIntent\n  ↓\nPolicy\n  ↓\nTenant AI Config\n  ↓\nData Sensitivity\n  ↓\nRequired Capability\n  ↓\nCost Budget\n  ↓\nLatency Target\n  ↓\nModel Health\n  ↓\nModel Route\n```\n\nResult:\n\n```ts\n{\n  provider: \"anthropic\";\n  model: \"claude-sonnet-x\";\n  gateway: \"cloudflare-ai-gateway\";\n}\n```\n\nTomorrow it may return:\n\n```ts\n{\n  provider: \"openai\";\n  model: \"gpt-x\";\n  gateway: \"internal-hermes\";\n}\n```\n\nNo product code changes.\n\n---\n\n## 8. Full Platform Contract\n\n```ts\ninterface PlatformRuntime {\n  auth: AuthProvider;\n  spine: SpineStore;\n  cache: CacheProvider;\n  objectStore: ObjectStore;\n  queue: QueueProvider;\n  vector: VectorStore;\n\n  ai: {\n    runtime: AIRuntime;\n    provider: AIProviderRegistry;\n    models: ModelRegistry;\n    gateway: AIGateway;\n    router: ModelRouter;\n\n    embeddings: EmbeddingProvider;\n    reranker: RerankProvider;\n    inference: InferenceProvider;\n\n    agents: AgentRuntime;\n    tools: ToolRuntime;\n\n    context: ContextProvider;\n    memory: MemoryProvider;\n\n    prompts: PromptRegistry;\n    guardrails: GuardrailProvider;\n    evaluation: EvaluationProvider;\n    observability: AIObservabilityProvider;\n  };\n}\n```\n\nConfiguration:\n\n```yaml\nplatform:\n  auth:\n    provider: descope\n\n  spine:\n    provider: postgres\n\n  cache:\n    provider: upstash\n\nai:\n  runtime: hermes\n\n  gateway:\n    provider: cloudflare-ai-gateway\n\n  routing:\n    provider: hermes-router\n\n  providers:\n    - anthropic\n    - openai\n    - google\n    - openrouter\n\n  embeddings:\n    provider: configurable\n\n  reranker:\n    provider: configurable\n\n  agents:\n    runtime: hermes\n\n  memory:\n    provider: continuity-memory\n\n  governance:\n    provider: iw-governance\n```\n\n---\n\n## 9. Provider Fabric\n\nThe Platform resolves these contracts:\n\n```ts\ninterface ProviderFabric {\n  auth: AuthProvider;\n  database: DatabaseProvider;\n  spineStore: SpineStoreProvider;\n\n  cache: CacheProvider;\n  queue: QueueProvider;\n  objectStore: ObjectStoreProvider;\n  vectorStore: VectorStoreProvider;\n  search: SearchProvider;\n\n  aiProvider: AIProviderRegistry;\n  modelProvider: ModelRegistry;\n  aiGateway: AIGateway;\n  modelRouter: ModelRouter;\n  embedding: EmbeddingProvider;\n  reranker: RerankProvider;\n  inference: InferenceProvider;\n\n  agentRuntime: AgentRuntimeProvider;\n  toolRuntime: ToolRuntimeProvider;\n  mcpRuntime: MCPRuntimeProvider;\n\n  connector: ConnectorProvider;\n  oauth: OAuthProvider;\n\n  email: EmailProvider;\n  notification: NotificationProvider;\n\n  billing: BillingProvider;\n  analytics: AnalyticsProvider;\n  observability: ObservabilityProvider;\n\n  secrets: SecretsProvider;\n  featureFlags: FeatureFlagProvider;\n}\n```\n\nProvider implementations may use Cloudflare, Supabase, Upstash, Descope, OpenAI, Anthropic, OpenRouter, Bedrock, or other vendors. **Those vendors do not define the platform domains.**\n\n---\n\n## 10. Final Platform Boundary\n\nProduct owns experience. Platform owns capability.  \nPlatform contracts are canonical. Providers are replaceable.  \nDeployment configuration selects infrastructure. Application architecture does not.\n\n```text\n┌──────────────────────────────────────────────────────────────────┐\n│                         PRODUCT PLANE                            │\n│                                                                  │\n│ Landing → Auth UX → Onboarding → Workbench → Governance → Twin  │\n│                                                                  │\n│ Product owns EXPERIENCE. It consumes Platform capabilities.      │\n└───────────────────────────────┬──────────────────────────────────┘\n                                │\n                         Platform SDK / API\n                                │\n┌───────────────────────────────▼──────────────────────────────────┐\n│                     INTEGRATEWISE PLATFORM                       │\n│                                                                  │\n│  01 IDENTITY       02 TENANCY        03 CONFIGURATION            │\n│  04 SPINE          05 MEMORY         06 CONTINUITY               │\n│  07 INTEGRATION    08 CAPABILITY     09 AI                       │\n│  10 GOVERNANCE     11 EXECUTION      12 COMMUNICATION            │\n│  13 COMMERCIAL     14 OPERATIONS     15 DEVELOPER                │\n│                                                                  │\n└───────────────────────────────┬──────────────────────────────────┘\n                                │\n                       Provider Contracts\n                                │\n┌───────────────────────────────▼──────────────────────────────────┐\n│                       PROVIDER PLANE                             │\n│                                                                  │\n│ Auth │ DB │ Cache │ Queue │ Storage │ Vector │ AI │ MCP │ OAuth │\n│ Mail │ Billing │ Analytics │ Observability │ Secrets │ Search    │\n│                                                                  │\n│                    ALL CONFIGURABLE                              │\n└──────────────────────────────────────────────────────────────────┘\n```\n\n### 10.1 Final 15 Platform Domains\n\n| #   | Platform domain   | Platform owns                                                                            |\n| --- | ----------------- | ---------------------------------------------------------------------------------------- |\n| 01  | **Identity**      | Auth contract, sessions, users, organizations, RBAC, service identity                    |\n| 02  | **Tenancy**       | Tenant lifecycle, isolation, memberships, environments, tenant context                   |\n| 03  | **Configuration** | Runtime config, provider config, tenant config, secrets refs, feature policy             |\n| 04  | **Spine**         | Canonical entity contracts, IDs, state ownership, entity graph, canonical writes         |\n| 05  | **Memory**        | User/Work/Org memory, promotion, compaction, retrieval, memory lifecycle                 |\n| 06  | **Continuity**    | Continuity Bridge, context bundles, hydration, workspace transition, operational history |\n| 07  | **Integration**   | Connector catalog, connection lifecycle, OAuth abstraction, sync, ingestion              |\n| 08  | **Capability**    | Capability registry, tools, actions, permissions, provider-backed capabilities           |\n| 09  | **AI**            | AI runtime, model registry, provider registry, gateway, router, embeddings, reranking    |\n| 10  | **Governance**    | Policy, evidence, approval, HITL, audit, AI/action permission boundaries                 |\n| 11  | **Execution**     | Jobs, workflows, queues, orchestration, retries, schedules, event execution              |\n| 12  | **Communication** | Email, notifications, webhooks, delivery channels, templates                             |\n| 13  | **Commercial**    | Plans, entitlements, metering, usage, billing abstraction                                |\n| 14  | **Operations**    | Observability, audit logs, health, analytics, telemetry, admin operations                |\n| 15  | **Developer**     | SDKs, API contracts, MCP exposure, webhooks, CLI, schemas, extension contracts           |\n\n---\n\n## 11. Live Repo Boundary\n\n**Platform Admin UI/page stays only in the live repo.**\n\nBoundary:\n\n```text\nLIVE REPO\n────────────────────────────\nLanding\nAuth UX\nOnboarding UX\nWorkbench\nGovernance Workbench\nTwin / AI Workbench\nPlatform Admin UI   ← HERE\nDeveloper UI\nConnector Marketplace UI\n\n             │\n             ▼\n\nPLATFORM SDK / GATEWAY\n\n             │\n             ▼\n\nPLATFORM REPO\n────────────────────────────\nAdmin APIs\nAdmin capabilities\nTenant operations\nProvider configuration\nRuntime configuration\nRBAC / policy\nBilling / entitlement control\nAI provider configuration\nModel registry\nGateway configuration\nConnector administration\nHealth / telemetry\nAudit\nOperational controls\n```\n\nLaw:\n\n> **Admin experience belongs to Live. Admin authority belongs to Platform.**\n\nThe live repo renders and orchestrates the Platform Admin page. The platform repo exposes the governed APIs, contracts, configuration, state, and operational capabilities behind it.\n\n---\n\n## 12. Development Boundary\n\n**Live repo becomes the contract consumer and mock execution environment.**  \n**Platform repo becomes the real capability implementation.**\n\n```text\nLive UI\n   ↓\nPlatform Client\n   ↓\nPlatform Contract\n   ↓\nResolver\n   ├── mock → Live mock endpoint\n   └── remote → Platform gateway\n```\n\nEndpoint namespace:\n\n```text\n/api/platform/v1/auth/*\n/api/platform/v1/tenants/*\n/api/platform/v1/spine/*\n/api/platform/v1/memory/*\n/api/platform/v1/continuity/*\n/api/platform/v1/integrations/*\n/api/platform/v1/capabilities/*\n/api/platform/v1/ai/*\n/api/platform/v1/governance/*\n/api/platform/v1/execution/*\n/api/platform/v1/communication/*\n/api/platform/v1/commercial/*\n/api/platform/v1/operations/*\n/api/platform/v1/admin/*\n```\n\n```env\nPLATFORM_MODE=mock\nPLATFORM_API_URL=/api/platform/v1\n```\n\nLater:\n\n```env\nPLATFORM_MODE=remote\nPLATFORM_API_URL=https://platform.integratewise.ai/api/v1\n```\n\n**No UI changes.**\n\n---\n\n## 13. Mock Endpoint Law\n\n> **Mock behavior may be fake. Contract, route, schema, status codes, pagination, errors, and state transitions must be real.**\n\nExample:\n\nIf the Platform contract is:\n\n```ts\nAccountEntitySchema.parse({\n  entityId: \"acc_001\",\n  tenantId: \"tenant_001\",\n  entityType: \"account\",\n  attributes: { name: \"Acme\" },\n  intelligence: { healthScore: 92 },\n  provenance: [],\n  version: 1,\n});\n```\n\nthen a mock returning only `{ name: \"Acme\", health: 92 }` is invalid. The mock must return the real contract shape.\n\n---\n\n## 14. Final Repo Shape\n\n```text\nintegratewise-platform/\n│\n├── services/\n│   ├── gateway\n│   ├── identity\n│   ├── tenancy\n│   ├── spine\n│   ├── memory\n│   ├── continuity\n│   ├── integration\n│   ├── capability\n│   ├── ai\n│   ├── governance\n│   ├── execution\n│   ├── communication\n│   ├── commercial\n│   └── operations\n│\n├── packages/\n│   ├── contracts\n│   ├── sdk\n│   ├── schemas\n│   ├── config\n│   ├── runtime\n│   ├── provider-core\n│   │\n│   ├── providers/\n│   │   ├── auth\n│   │   ├── database\n│   │   ├── cache\n│   │   ├── queue\n│   │   ├── storage\n│   │   ├── vector\n│   │   ├── search\n│   │   ├── ai\n│   │   ├── gateway\n│   │   ├── connector\n│   │   ├── oauth\n│   │   ├── email\n│   │   ├── billing\n│   │   └── observability\n│   │\n│   ├── ai-sdk\n│   ├── continuity-sdk\n│   ├── governance-sdk\n│   ├── integration-sdk\n│   └── capability-sdk\n│\n├── migrations/\n├── deployments/\n├── scripts/\n└── docs/\n```\n\n---\n\n## 15. The Five Architecture Laws\n\n1. **Product owns experience. Platform owns capability.**\n2. **Platform contracts are canonical; providers are replaceable.**\n3. **No provider SDK crosses into product code or domain services outside its adapter.**\n4. **No model, agent, connector, or workflow writes directly to Spine. Canonical writes cross the governed state boundary.**\n5. **Deployment configuration selects infrastructure; application architecture does not.**\n\n---\n\n## Canonical Source Status\n\n| Doc                                            | Status                                        |\n| ---------------------------------------------- | --------------------------------------------- |\n| `docs/CANON.md`                                | Canonical index                               |\n| `docs/architecture/PRODUCT_ARCHITECTURE.md`    | Canonical                                     |\n| `docs/architecture/WORKBENCH_DOCTRINE.md`      | Canonical                                     |\n| `docs/architecture/v2-ai-capability-fabric.md` | **Final AI / Provider Independence boundary** |\n\nWhen conflict arises between this document and prior docs, this document is canonical.\n"}