{"slug":"strategy/product-strategy/ARCHITECTURE_CANONICAL","title":"IntegrateWise Architecture Document","section":"strategy","sectionLabel":"Strategy","status":"unclassified","type":"document","path":"strategy/product-strategy/ARCHITECTURE_CANONICAL.mdx","bytes":30651,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** CANONICAL — Supersedes all prior architecture descriptions  \n**Authority:** Nirmal, Founder  \n**Date:** May 28, 2026 | Updated June 3, 2026\n\n---\n\n## Problem\n\nModern work is fragmented across CRMs, support desks, communication tools, documentation systems, project trackers, and AI interfaces, which forces the human to become the integration layer between systems that do not share context.\n\nIn this model, AI repeatedly starts cold, workflows break when context is missing, and the user must continuously re-inject knowledge that no system persists operationally.\n\nIntegrateWise is designed to solve that deeper operating-model problem by creating persistent, operational, model-independent memory that keeps AI and human work aligned across sessions, tools, models, providers, and infrastructure changes.\n\n---\n\n## Architectural Thesis\n\nIntegrateWise is built on a simple thesis: humans and machines enter through different channels, but both converge into the same Spine, the same memory system, and the same governed decision model.\n\nThe interaction layer is dual-channel, the persistence layer is singular, and the projection layer surfaces the same underlying truth into three product surfaces designed for different modes of work.\n\nThis architecture positions IntegrateWise not as a chat interface, not as a workflow engine, and not as a dashboard, but as an operating environment where context is unified, memory persists, continuity survives change, and governance remains intact.\n\n---\n\n## Interaction Model\n\nIntegrateWise has two channels of entry.\n\n| Channel         | Entry Actor                 | Interface                                                                                | Purpose                                                                      |\n| --------------- | --------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |\n| Human channel   | User                        | Natural language plus direct tool interaction through the Twin and Operational Workbench | Lets the user reason, inspect, edit, approve, and operate on projected truth |\n| Machine channel | External tools and software | MCP pipeline                                                                             | Lets connected systems send data into IntegrateWise in a canonical way       |\n\nOn the human side, the user speaks in natural language, invokes tools, and works directly on projected data in the Operational Workbench while the Twin reasons over the same Spine-backed memory.\n\nOn the machine side, connected systems enter through MCP, which serves as the primary protocol boundary for software-to-software communication into IntegrateWise.\n\n---\n\n## Connection Layer\n\nThe connection layer has three distinct components that together maintain ingestion and continuity across the ecosystem.\n\n| Component                         | Role                                                                                                                                |\n| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |\n| MCP Pipeline                      | Primary connector for tools and software; protocol-level bridge for inbound and outbound tool communication                         |\n| Folder / File / Location Watchers | Passive ingestion paths that fetch records and files from designated locations into the Spine                                       |\n| AI Connectors                     | Active bidirectional read/write paths that maintain file continuity, data continuity, and tool-to-tool continuity through workflows |\n\nLoader and Normalizer are not alternatives to MCP; they are internal stages of IntegrateWise's MCP implementation. Watchers complement that protocol path by bringing records and files into the system from designated locations, while AI connectors maintain active bidirectional continuity between tools and the Spine through workflow-driven interactions.\n\n---\n\n## MCP Pipeline\n\nThe inbound machine flow through the protocol layer is:\n\n```\nExternal Tool\n│\n▼\nMCP ──── Loader (fetch) ──── Normalizer (transform) ──── Spine\n```\n\nMCP is the boundary contract, Loader is the fetch stage, and Normalizer is the transformation stage that reformats heterogeneous source data into a common internal shape before it lands in the Spine.\n\nIntegrateWise uses real MCP. Loader and Normalizer are appended as part of its implementation rather than presented as a proprietary alternative.\n\n---\n\n## Data Flow\n\nIntegrateWise operates as a continuous round trip, not a one-way ingestion system. Data enters from tools, watchers, and connected locations, gets normalized, lands in the Spine, is projected into product surfaces, gets acted on by the user, and then maintains continuity back across the ecosystem through governed handoff and bidirectional connector paths.\n\nThe top-level flow is:\n\n```\nHUMAN                                    TOOLS / SOFTWARE / LOCATIONS\n│                                                  │\n│ NLP + Tools                                      │ MCP / Watchers / AI Connectors\n▼                                                  ▼\nOperational Workbench / Twin                        Loader → Normalizer / Watchers / Connector Flows\n└──────────────────────┬──────────────────────────────┘\n                       ▼\n                     Spine\n                       ▼\n             Projection into Surfaces\n                       ▼\n          User review, approval, planning\n                       ▼\n        Handoff to user's agentic claw\n                       ▼\n       User executes in their own stack\n                       ▼\n    Continuity returns through connectors/watchers\n```\n\nThis round trip is central to the architecture because continuity is only real when the system can absorb change from tools and files, preserve memory through the Spine, and maintain aligned state across future cycles.\n\n---\n\n## Spine\n\nThe Spine is the core persistence layer of IntegrateWise. It is not a single database but a living record implemented as one logical memory layer across multiple physical storage systems, including Postgres, Redis, Cloudflare KV, Cloudflare R2, Cloudflare D1, and a Spine DB-managed database that is accessed only through a Cloudflare Worker.\n\nDifferent data types live in different storage layers according to their access patterns, but the architecture presents them as one coherent memory to every layer above. This is what allows the system to survive model switches, provider switches, and infrastructure changes without forcing the user to re-explain context.\n\n---\n\n## Surface Model\n\nIntegrateWise surfaces the Spine through three product surfaces.\n\n| Surface               | What It Is                                                                                                                                                                                                                            |\n| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Operational Workbench | Primary work surface where projected truth is shown and work happens. Left sidebar navigation. The Twin is a collapsible sidebar that pops out only when needed — surfacing insights, requesting approvals, executing actions inline. |\n| Twin Workbench        | Full AI ecosystem surface — skills, knowledge, agents, prompts, conversational library. OpenWebUI-style. Conversational memory lives here. Can be positioned at different locations in the shell.                                     |\n| Memory View           | Personal, Organizational, and Conversational memory surfaced in a documentation-site style. Can be positioned at different locations.                                                                                                 |\n\nThe Operational Workbench is the primary work surface. Left sidebar navigation. Domain-specific views (BizOps, Account Success, Sales, Finance, etc.). The Twin is a collapsible sidebar that pops out only when needed — surfacing insights, requesting approvals, and executing actions inline without occupying permanent screen space. Business Operations is a department within the Operational Workbench — 14 modules, cross-department rollup, founder/CEO/COO/CTO lenses.\n\nThe Twin also exists independently in the Twin Workbench as the full AI ecosystem surface — skills, knowledge, agents, prompts, conversational library. OpenWebUI-style. Conversational memory lives here. Can be positioned at different locations in the shell.\n\n---\n\n## Memory Model\n\nIntegrateWise uses three memory layers: Personal Memory, Organizational Memory, and Conversational Memory. These are persistent memory layers, not temporary context windows, and they survive model changes, provider changes, and session boundaries.\n\n| Memory Layer          | Purpose                                                                                        | Surfacing and Sharing                                                                                              |\n| --------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |\n| Personal Memory       | Private preferences, personal context, notes, and working patterns belonging to the user alone | Hard-separated from organizational memory; surfacable through internal views and user-owned connectors             |\n| Organizational Memory | Shared institutional knowledge, decisions, patterns, doctrine, and team-level intelligence     | Shared at company level with governed promotion paths; surfacable through internal views and user-owned connectors |\n| Conversational Memory | Staging layer for interactions, discussions, raw decisions, and working context                | Surfaced within the Twin Workbench; not a separate surface                                                         |\n\nThe key architectural principle is that memory stays independent by design; sharing is not automatic and is not an architectural leak path. Information moves between layers only through governed promotion, explicit user action, or AI recommendation followed by human approval.\n\nPersonal and Organizational Memory are surfacable not only inside IntegrateWise views but also through user-owned connectors, allowing users to access their memory from their own tools and systems without collapsing the underlying separation model. Conversational Memory lives inside the Twin Workbench and serves as the staging layer between interaction and permanent knowledge.\n\n---\n\n## Governance\n\nGovernance is not a wrapper added on top of the system; it is part of the architecture at every layer. The governing principle is simple: AI proposes, human approves, and execution happens only after handoff into the user's own environment.\n\nEvery action has lineage, every decision is recorded, approval gates exist before execution, and governed promotion ensures that memory movement is reviewed before becoming permanent. IntegrateWise reasons, plans, and prepares actions, but execution remains outside the product boundary and is carried out by the user through their own agentic claw and stack.\n\nThe handoff model is:\n\n```\nTwin reasons and plans\n│\n▼\nHandoff to user's agentic claw\n│\n▼\nUser executes in their own stack\n```\n\n---\n\n## Security and Control\n\nIntegrateWise secures external machine access to the ecosystem through Cloudflare Access at the perimeter, routes every authenticated request through a tenant-aware Gateway, and keeps internal service execution inside Cloudflare through private Worker-to-Worker bindings. This creates a clean three-part security and runtime model: Access verifies who is calling, the Gateway determines what tenant and capabilities the caller is allowed to reach, and the internal services execute platform logic without exposing private coordination paths to the public internet.\n\nFor machine-to-machine MCP traffic, the correct pattern is to protect the public MCP entrypoint with a Cloudflare Access **Service Auth** policy rather than an interactive browser login flow. MCP clients, agent runtimes, and external services must therefore authenticate using `CF-Access-Client-Id` and `CF-Access-Client-Secret`, allowing JSON-RPC, SSE, and similar machine protocols to cross the Access membrane without being broken by a human login redirect. Where a hostname is already covered by an existing Access application, the Service Auth policy should be attached to that application instead of creating a second overlapping application definition, because overlapping scopes can produce blocking or inconsistent behavior.\n\nOnce Access has authenticated the caller, the request enters the Gateway, where IntegrateWise resolves tenant context and enforces application-level authorization. The `x-tenant-id` header may be passed through to the Gateway, but tenant trust is not something Cloudflare validates on your behalf; the Gateway must verify that the authenticated client is actually allowed to operate against the requested tenant boundary before exposing tools, actions, memory, or Spine partitions. In IntegrateWise terms, Access is the perimeter membrane, but tenant isolation remains a governed platform responsibility inside the system.\n\nInside the ecosystem, service-to-service execution uses Cloudflare Service Bindings or Workers RPC rather than public URLs. In that mode, one Worker calls another through Cloudflare’s internal runtime path, which means the request does not traverse the public internet and does not pass back through the Access-protected hostname. This distinction matters: external MCP clients always authenticate through Access, while internal IntegrateWise services communicate privately through bindings, preserving speed, reducing surface area, and keeping the internal nervous system separate from public ingress.\n\nThe operational rule is therefore simple and final: all external MCP traffic enters through an Access-protected public endpoint using Service Auth; all tenant interpretation and authorization happen inside the Gateway; and all internal platform coordination happens through private Worker bindings. This is the correct Cloudflare-native pattern for a Spine-powered, multi-tenant MCP architecture because it separates perimeter authentication, tenant governance, and internal execution into distinct layers without collapsing them into one mechanism.\n\n### Canonical Doctrine Block\n\n> IntegrateWise treats Cloudflare Access as the authentication membrane for all external machine traffic, the Gateway as the tenant and capability router for all authenticated requests, and Cloudflare Service Bindings as the private execution path for internal services. External MCP clients must authenticate with Service Auth credentials so JSON-RPC and SSE connections remain machine-safe; internal Workers never use the public MCP hostname and instead communicate through private bindings inside Cloudflare’s runtime. This separation is the governing rule of the ecosystem: perimeter authentication at Access, tenant enforcement in the Gateway, and private coordination inside the platform.\n\n### Security Terminology\n\n- **Access membrane**: The Cloudflare Access boundary where external machine callers are authenticated before entering IntegrateWise.\n- **Gateway**: The tenant-aware routing and authorization layer that decides what an authenticated caller may see or do.\n- **Private nervous system**: The internal Worker-to-Worker execution path implemented through Service Bindings or Workers RPC.\n- **Spine-aligned ingress**: The rule that every external call enters through one governed perimeter before touching tenant memory, tools, or records.\n\n---\n\n## MCP OAuth Resource Server\n\nIntegrateWise exposes its external MCP interface as an OAuth-protected MCP resource server. The MCP host publishes Protected Resource Metadata, directs clients to the authorization server through standard OAuth discovery, and accepts only bearer tokens issued for the IntegrateWise MCP resource. Tenant routing remains a gateway responsibility after token validation, while internal platform services continue to communicate through private Worker bindings rather than the public MCP ingress.\n\n### Target Architecture\n\n```\nExternal MCP Client (Cursor, Claude, Agent Runtime)\n        │\n        │ 1. Discovery\n        ▼\nmcp.integratewise.ai/.well-known/oauth-protected-resource\n        │\n        │ 2. Redirect to Authorization Server\n        ▼\nauth.integratewise.ai/.well-known/oauth-authorization-server\n        │\n        │ 3. Authorization Code Flow → Token\n        ▼\nClient receives Bearer token (aud: https://mcp.integratewise.ai)\n        │\n        │ 4. Authenticated MCP Call\n        ▼\nmcp.integratewise.ai (Gateway validates token → tenant scope → MCP tools)\n```\n\nFour components make this work:\n\n| Component                                      | Role                                                                                                 |\n| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| MCP Resource Server (`mcp.integratewise.ai`)   | Serves MCP endpoints + Protected Resource Metadata                                                   |\n| Authorization Server (`auth.integratewise.ai`) | OAuth discovery, authorize, token, dynamic client registration                                       |\n| Protected Resource Metadata                    | `/.well-known/oauth-protected-resource` with `resource`, `authorization_servers`, `scopes_supported` |\n| Bearer Token Validation                        | Gateway validates issuer, audience, expiry, scopes before exposing tenant-scoped tools               |\n\n### What Must Exist on the MCP Host\n\n- `/.well-known/oauth-protected-resource` returning JSON with `resource`, `authorization_servers`, and `scopes_supported`.\n- A `401 Unauthorized` response on unauthenticated MCP calls with `WWW-Authenticate: Bearer ... resource_metadata=...` pointing to the protected-resource metadata URL.\n- Bearer-token validation inside the gateway for every call, including **audience restriction** so tokens are explicitly meant for `https://mcp.integratewise.ai`.\n- Tenant authorization enforced after token validation — `x-tenant-id` header checked against token claims or server-side entitlement map, never trusted alone.\n\n### Token Model Rules\n\n- `aud` must equal `https://mcp.integratewise.ai`.\n- Scopes are narrow and purpose-specific: `mcp:tools`, `mcp:resources`, `tenant:read`, `tenant:write`, `memory:read`, `memory:write`.\n- `x-tenant-id` is validated against token claims or entitlement map, not trusted as a standalone header.\n- Internal Worker-to-Worker traffic continues through Service Bindings, never through OAuth over the public hostname.\n\n### Implementation Path on Cloudflare\n\nThe most practical production path for IntegrateWise:\n\n- Keep Cloudflare Access for human/admin surfaces if desired, but do not rely on it as the MCP OAuth layer.\n- Stand up a proper OAuth authorization server, either:\n  - **Cloudflare Workers OAuth Provider** for a Cloudflare-native implementation, or\n  - an external IdP such as Keycloak/Auth0/Descope/Keycard for faster standards-complete rollout.\n- Implement the MCP server on Workers so it serves both the MCP endpoint and the protected-resource metadata endpoints on the same host.\n\n### Build Checklist\n\n- [ ] Create an OAuth issuer for IntegrateWise.\n- [ ] Publish auth metadata at `auth.integratewise.ai/.well-known/oauth-authorization-server` or OIDC discovery.\n- [ ] Add `/.well-known/oauth-protected-resource` to `mcp.integratewise.ai`.\n- [ ] Make unauthenticated MCP requests return `401` with `WWW-Authenticate` and `resource_metadata`.\n- [ ] Validate bearer tokens in the gateway using issuer JWKS or introspection.\n- [ ] Enforce audience = `https://mcp.integratewise.ai`.\n- [ ] Enforce tenant authorization after token validation.\n- [ ] Keep internal services on Service Bindings.\n\n---\n\n## Product Ecosystem\n\nIntegrateWise is built across multiple repositories that each own a distinct responsibility. No single repo contains the entire product; the system emerges from the interaction between them.\n\n```\nFolder Monitor (laptop/server)\n        ↓ detects files, events, changes\n        ↓ writes to QUEUE\nQueue + Routing layer\n        ↓ promotion logic, error logging\n        ↓ routes to correct destination\n        ↓\n┌───────────────────────────────────────────────────────┐\n│ INTAKE                 GOVERNANCE                     │\n│ Downloads/Desktop/Docs  System proposes               │\n│ → staging queue        Human approves                 │\n│ → never auto-moves     Audit log every action         │\n└───────────────────────────────────────────────────────┘\n        ↓\n┌─────────────────────────────────────────────────────────────────┐\n│  THE FULL PRODUCT                                               │\n│                                                                 │\n│  IntegrateWise - Memory          ← THE SUBSTRATE                │\n│  → Conversational + Org + Personal memory unified               │\n│  → The vault. The thing that cannot be deleted.                 │\n│                                                                 │\n│  integratewise-live               ← THE ENGINE                  │\n│  → 25 CF workers, 8-stage pipeline, HITL loop,                 │\n│    Entity 360, knowledge service, Think/Govern/Act,             │\n│    Stripe+Razorpay billing, 50+ connectors                      │\n│                                                                 │\n│  integratewise-ops                ← PROVEN SURFACES              │\n│  → Founder Command Center, IntegrationHealth, Tool ROI          │\n│                                                                 │\n│  IntegrateWise Folder Monitor     ← INTAKE PIPE                 │\n│  → Files, events, changes enter the system here                 │\n│                                                                 │\n│  integratewise-docs               ← PUBLIC DOCS                 │\n│                                                                 │\n│  integratewise-marketing          ← MARKETING SITE              │\n│                                                                 │\n│  EXCEPTION: Twin memory wiring (behavioral logging →            │\n│  personal memory → prompt injection)                             │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### Repository Contributions\n\n| Repository                   | What It Contributes                                                                               |\n| ---------------------------- | ------------------------------------------------------------------------------------------------- |\n| IntegrateWise - Memory       | The substrate — canonical memory vault that the folder monitor feeds into and the Twin reads from |\n| integratewise-live           | The engine — pipeline, memory, governance, billing, connectors, 25 CF Workers                     |\n| integratewise-ops            | The operational truth — proven working surfaces, 28 connected systems, founder view               |\n| IntegrateWise Folder Monitor | The intake pipe — files, events, changes enter the system here                                    |\n| integratewise-docs           | Public documentation site                                                                         |\n| integratewise-marketing      | Marketing site with Sanity CMS                                                                    |\n\n---\n\n## Assembly Sequence\n\nThe product is assembled in five phases, each building on the previous one.\n\n**Phase 1 — Intake pipe (Folder Monitor + Queue)**\nFolder Monitor runs on laptop/server. Detects. Writes to queue. Never acts. Queue routes to correct service based on file type, source, content. Error log captures every failure. This is the entry point for all external data.\n\n**Phase 2 — Routing layer**\nQueue consumer reads each item. Classifies: is this a document (Flow B), a webhook event (Flow A), an AI session (Flow C)? Routes to correct service. Promotion logic: when does a staged file become canonical? Only on human approval.\n\n**Phase 3 — Wire the ops surfaces**\nTake what was built (Founder Command Center, IntegrationHealth, Tool ROI, Brainstorming Layer) and wire them to integratewise-live's backend. The ops surfaces had the right interfaces on the wrong stack. The backend has the right stack with surfaces missing. Merge the two.\n\n**Phase 4 — Twin memory (the 5% exception)**\nBehavioral logging → personal memory schema → prompt injection. This is what makes the Twin a Twin and not a chatbot. Cannot be skipped — but it goes after the intake pipe is solid.\n\n**Phase 5 — The combined shell**\nOne shell that houses all of it. OS cockpit as the frame. Domain shells as the rooms. Knowledge base as the memory. Folder monitor as the intake. Twin as the operator. Approval gate on every action.\n\n---\n\n## MCP as Protocol, Not Architecture\n\nA core insight distinguishes IntegrateWise from every other MCP implementation: the architecture was built from the data problem backward, not from the protocol forward.\n\nMost systems implementing MCP start with the protocol — \"how do tools speak to the LLM?\" — and expose whatever data their existing schema already has. The result is fragmented, tool-specific context that still leaves the LLM partially blind.\n\nIntegrateWise started with the data problem — \"the LLM needs the full picture\" — and built the architecture to produce that. The Normalizer and Spine were built in August 2025, before MCP was published as a protocol specification. The founding insight was not \"implement MCP.\" The founding insight was \"normalize everything and hold one truth.\"\n\nThis produces what can be called **proof by convergence**: two independent derivations — one starting from the protocol spec, one starting from the data problem — arrive at exactly the same architecture. When two different paths lead to the same result, that result is not a preference or a design choice. It is the answer the problem structurally demands.\n\nThe practical implication: MCP is the protocol that makes normalization native and uniform. But the intelligence was already there the moment the decision was made — one truth, one source, everything normalized. MCP is what makes it elegant. The Normalizer and Spine are what make it real.\n\n```\nFragmented data → blind LLM\nNormalized data → LLM sees everything\n\nIt does not matter what carries\nthe normalized data to the LLM.\nThe normalization is the insight.\nThe single truth is the insight.\nThe protocol is just the delivery mechanism.\n```\n\n---\n\n## Continuity Across Change\n\nA defining property of the architecture is continuity across sessions, tools, files, models, providers, and infrastructure. The model is treated as a variable and the memory as a constant, which means switching from one LLM to another does not reset the system's understanding.\n\nThat continuity is maintained not only through the Spine but also through AI connectors and watcher-based ingestion paths that preserve file continuity, data continuity, and tool-to-tool continuity across the operating environment. In IntegrateWise, continuity is not a feature flag; it is the foundation that connects the Spine, the memory layers, the three-surface model, and the governance model into one coherent operating environment.\n\n---\n\n## Architectural Summary\n\nIntegrateWise can be summarized as a top-down architecture with five linked layers.\n\n1. **Problem layer:** fragmented tools, cold-start AI, and human-held context.\n2. **Interaction layer:** humans enter through NLP and tools; machines and software enter through MCP, watchers, and connector paths.\n3. **Processing layer:** Loader fetches, Normalizer transforms, and all inbound continuity paths converge into the Spine.\n4. **Surface and memory layer:** the Spine persists truth and projects it into the Operational Workbench, Twin Workbench, and Memory View, backed by personal, organizational, and conversational memory.\n5. **Governance layer:** every action, promotion, and handoff passes through approval, lineage, and control before the user executes in their own stack.\n\nThe security layer sits across all five: Cloudflare Access authenticates external machine traffic at the perimeter, the Gateway resolves tenant context and enforces authorization after token validation, the MCP endpoint publishes OAuth Protected Resource Metadata and accepts only bearer tokens with audience restriction, and all internal platform coordination runs through private Worker bindings with no public ingress.\n\nTogether, these layers define IntegrateWise as a unified operating environment where users work in one place, memory persists across change, continuity extends across the ecosystem, and execution remains under explicit human control outside the product boundary.\n\n---\n\n_Document: IntegrateWise Architecture — Canonical_  \n_Author: Nirmal, Founder_  \n_Status: Supersedes ARCHITECTURE_V2.md and all prior architecture descriptions._  \n_Date: May 28, 2026 | Updated June 3, 2026_\n"}