{"slug":"internal/architecture/INTEGRATEWISE_ARCHITECTURE_v2.2","title":"IntegrateWise Architecture v2.2","section":"internal","sectionLabel":"Internal","status":"unclassified","type":"document","path":"internal/architecture/INTEGRATEWISE_ARCHITECTURE_v2.2.mdx","bytes":13005,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** CANONICAL  \n**Date:** 2026-08-11  \n**Supersedes:** previous architecture locks, consolidated contracts and canonical/final architecture framings where they conflict.\n\n## 1. Product statement\n\nIntegrateWise is an Operational Continuity Platform. It preserves governed business context across systems, humans, models and agents while keeping execution bounded by explicit authority.\n\nThe surface/product boundary is:\n\n```text\nOne Auth → User Workbench → contextual Twin → Tool Capabilities\n```\n\nThe platform underneath is:\n\n```text\nProduct Package + Platform Backend + Governed Spine + Execution Runtime\n```\n\n## 2. System boundary\n\n```text\nHOST\nidentity + connected apps + connector authority\n  ↓\nONE AUTH\necosystem entry + session/tenant/delegation binding\n  ↓\nPRODUCT PACKAGE\nDiscovery + Capabilities + Spine Cache + ADK + Orchestrator\n+ Business Context + Loader + Normalizer + MCP Connector + Tool Capability\n  ↓\nFRONTEND RUNTIME\nshared Auth + Connectors + MCP + Platform context\n+ frontend-owned domain/product projection\n  ↓\nUSER WORKBENCH / OTHER FRONTENDS\nphase/lifecycle projection + continuity + Twin + Execution Mode\n  ↓\nPLATFORM BACKEND\nPackage Control Plane + Services + AI + Agents + Memory + Pipelines\n  ↓\nGOVERNED EXECUTION\nGovernance → orchestrated execution/Hermes → provider → reconciliation\n```\n\n## 3. Ownership matrix\n\n| Concern                  | Owner                                                | Must not own                                        |\n| ------------------------ | ---------------------------------------------------- | --------------------------------------------------- |\n| Host identity            | Host / One Auth trust boundary                       | Provider business data truth                        |\n| Provider credentials     | Host connector authority / approved credential vault | Workbench, agents, Twin, projection records         |\n| Connector projection     | IntegrateWise projection registry                    | Raw provider refresh tokens                         |\n| Canonical business truth | Business Context / governed Spine writers            | Memory, UI state, agents                            |\n| Operational cache        | Spine Cache / D1/KV                                  | Irreplaceable canonical history                     |\n| Memory                   | Platform Memory                                      | Canonical operational truth                         |\n| Frontend shared runtime  | Auth + Connector + MCP + Platform services           | Domain-specific UI ownership                        |\n| Domain frontend          | Domain/product UX and projection composition         | Separate identity, connector, MCP or platform truth |\n| Workbench composition    | Projection Engine                                    | Provider credentials or canonical writes            |\n| Capability contract      | Capability Manager / registry                        | Policy bypass                                       |\n| Execution authority      | Governance                                           | Model confidence                                    |\n| Execution coordination   | Orchestrator / Hermes                                | Approval policy ownership                           |\n| Outcome reconciliation   | Sync/Pipeline/Spine promotion                        | Client-side optimistic truth                        |\n\n## 4. One Auth\n\nOne Auth is the ecosystem entry. It validates host identity/session assertions, resolves tenant membership and binds the user to IntegrateWise without duplicating host-owned connector authority.\n\nA connector projection contains references, effective capability grants, policy bindings, health/lifecycle state, schema/version metadata and tenant/principal constraints. It does not contain provider refresh tokens, provider client secrets or unrestricted host authority.\n\n## 5. Product Package\n\nEach Product Package composes ten responsibilities:\n\n1. **Discovery** — packages, connector projections, schemas, MCP endpoints, capabilities, versions and health.\n2. **Capabilities** — typed/versioned effective operations available to the current principal/context.\n3. **Spine Cache** — rebuildable, freshness-aware materialized operational state.\n4. **ADK** — stable runtime/developer kernel for context, capability invocation, lifecycle, policy hooks and telemetry.\n5. **Orchestrator** — durable workflows, retries, compensation, approvals, tools, services and bounded agent tasks.\n6. **Business Context** — canonical semantic entities, relationships, assertions, provenance, temporal validity and policy metadata.\n7. **Loader** — extraction, pagination, webhooks, cursors, raw envelopes, checkpoints and replay.\n8. **Normalizer** — provider-to-canonical mapping, validation, deduplication, identity resolution and lineage.\n9. **MCP Connector** — governed MCP exposure/consumption and protocol translation.\n10. **Tool Capability** — typed executable operation with schema, side-effect class, policy, idempotency, version and audit contract.\n\n## 6. Shared frontend architecture\n\nEvery IntegrateWise frontend shares the same four platform capabilities:\n\n```text\nAuth + Connectors + MCP + Platform\n```\n\nThe rest of the frontend may be independently owned.\n\n```text\nFrontend\n├── Shared Auth\n├── Shared Connectors\n├── Shared MCP\n├── Shared Platform access\n└── Frontend-owned domain/product UX and projections\n```\n\nA frontend may customize presentation, navigation and domain workflows, but it may not create an independent identity authority, connector registry, MCP registry, capability definition source, Governance truth or canonical business store.\n\nReplacing a frontend must not require users to reauthenticate into a new ecosystem identity, reconnect provider accounts, redefine MCP capabilities or migrate Platform Backend truth.\n\nSee [`SHARED_FRONTEND_SHELL_AND_DOMAIN_OWNERSHIP.md`](SHARED_FRONTEND_SHELL_AND_DOMAIN_OWNERSHIP.md).\n\n## 7. User Workbench and frontend projections\n\nThere is one User Workbench product surface, while other frontends may own their own domain/product experiences. Role, department, industry, entity, subdomain, lifecycle and phase alter projections; they do not create independent truth models.\n\nThe frontend is projection-based:\n\n```text\nbackend canonical tables\n+ relationships\n+ lifecycle / phase\n+ continuity\n+ tenant / RBAC\n+ connector availability\n+ Tool Capability availability\n→ Projection Engine\n→ frontend view\n```\n\nEvery frontend route must identify its lifecycle, phase, primary backend tables, supporting tables/relationships, continuity inputs, filters, projected capabilities, write path and rehydration trigger.\n\nThe Twin is a contextual cognitive capability inside the Workbench. It can read grounded context, reason, draft and propose. It cannot bypass Governance or write canonical truth directly.\n\nSee [`LIFECYCLE_CONTINUITY_AND_PROJECTION_MAP.md`](LIFECYCLE_CONTINUITY_AND_PROJECTION_MAP.md).\n\n## 8. Lifecycle, phases and continuity\n\nUser flow and execution are phase-, lifecycle- and continuity-driven rather than page-first.\n\nThe generic operating loop is:\n\n```text\nResume\n→ Orient\n→ Decide\n→ Govern\n→ Execute\n→ Reconcile\n→ Transition\n→ Continue\n```\n\nA lifecycle is durable backend progression. A phase is the current operational slice of that lifecycle. Continuity is the bounded state needed to resume the work across users, systems, hosts, sessions and agents.\n\nCapability availability is phase-aware:\n\n```text\nentity + lifecycle_stage + phase\n+ connector/capability availability\n+ tenant policy + RBAC\n→ available Tool Capabilities\n```\n\nA connector's technical capability alone is insufficient to expose an action. The action must be valid for the current business lifecycle phase.\n\n## 9. Execution Mode\n\nEvery capability invocation follows:\n\n```text\nselect capability\n→ bind entity/subdomain + lifecycle/phase context\n→ validate schema, connector availability and policy inputs\n→ optional dry-run\n→ Governance\n   ├─ allowed\n   ├─ approval_required\n   └─ blocked\n→ execute when authorized\n→ structured result\n→ telemetry + evidence + audit\n→ reconciliation\n→ lifecycle transition when validated\n→ continuity update\n→ outcome promotion\n→ projection rehydrate\n```\n\nGovernance is always mandatory. Approval is conditional on policy.\n\n- `allowed`: explicitly pre-authorized, narrowly bounded execution.\n- `approval_required`: proposal must receive a scoped human approval artifact before execution.\n- `blocked`: execution denied.\n\nConsequential external mutations should default to `approval_required`.\n\n## 10. Platform Backend\n\nPlatform Backend consists of:\n\n- Package Control Plane\n- Services\n- AI\n- Agents\n- Memory\n- Pipelines\n\nThe Platform Management Console configures and operates these capabilities. It is distinct from the User Workbench and other product/domain frontends.\n\n## 11. Platform Management Console\n\nCanonical modules:\n\n- Integration Manager\n- Connector Marketplace\n- Activation Hub\n- Capability Manager\n- MCP Pool\n- AI Models\n- Knowledge\n- Memory & Continuity\n- Automation\n- Pipelines\n- Governance\n- Observability\n- Administration\n  - Organizations\n  - Users\n  - Roles\n  - Permissions\n  - Audit\n  - Billing\n  - Deployments\n  - API Keys\n  - Security\n\nConnector-aware routing is a hard constraint across Configuration, Activation, Integration, Discovery and Schema flows.\n\n## 12. Truth and storage\n\n- Canonical governed business truth belongs in Neon/Postgres through approved writers/pipelines.\n- Durable business entity families belong in semantic tenant-scoped backend tables.\n- Frontend destinations are projections; do not create page-shaped truth tables solely for UI convenience.\n- D1/KV may hold bounded, reconstructable operational state and Spine Cache materializations.\n- Object storage may hold evidence bytes while canonical metadata/lineage remains governed.\n- Memory is subordinate to canonical business truth.\n- AI/model outputs are candidates/proposals until governed promotion.\n\n## 13. Runtime sequence\n\n```text\nHost identity/grants\n→ One Auth\n→ Discovery\n→ connector projections\n→ Loader\n→ Normalizer\n→ Business Context / Spine promotion\n→ Spine Cache\n→ lifecycle + continuity composition\n→ Projection Engine\n→ shared frontend runtime (Auth + Connectors + MCP + Platform)\n→ frontend-owned projection\n→ Twin/user intent\n→ phase-valid Tool Capability\n→ Governance\n→ Orchestrator/Hermes\n→ provider/internal service\n→ Sync/reconciliation\n→ lifecycle transition\n→ continuity/timeline update\n→ outcome promotion\n→ refreshed projection\n```\n\n## 14. Invariants\n\n1. One Auth is the ecosystem entry.\n2. Host connector authority is not duplicated.\n3. Connector projections never contain copied provider secrets.\n4. Every frontend shares Auth + Connectors + MCP + Platform runtime capabilities.\n5. Domain/product frontends may own the remaining UX and projection composition.\n6. Replacing a frontend must not require migrating identity, connectors, MCP definitions or Platform Backend truth.\n7. Frontends project backend canonical tables; they do not own independent business truth.\n8. Every frontend route has a backend table/projection map.\n9. User flow and execution are lifecycle-, phase- and continuity-driven.\n10. Twin is contextual and non-authoritative.\n11. Business Context/Spine owns canonical business truth.\n12. Memory does not silently become truth.\n13. Tool Capabilities are first-class executable contracts.\n14. Capability availability is phase-aware, connector-aware and policy-aware.\n15. Every execution passes Governance.\n16. `approval_required` requires a scoped human approval artifact.\n17. `allowed` is explicit policy, not a bypass.\n18. Agents/models do not directly own provider credentials or canonical write authority.\n19. Outcomes are reconciled before becoming canonical.\n20. Reconciliation may drive validated lifecycle transition and continuity update.\n21. Connector-aware routing is mandatory across lifecycle/configuration flows.\n22. Public/client surfaces do not own provider credentials or canonical workflow truth.\n23. Generated/public documentation never overrides source documentation.\n\n## 15. Environment promotion\n\nThe same versioned artifacts progress through:\n\n```text\nDevelopment → Customer Zero → Customer Production\n```\n\nOnly code, packages, schemas, manifests, policies/defaults and versioned configuration definitions move forward. Tenant data, secrets, runtime caches, queues, evidence and audit records do not.\n\n## 16. Change policy\n\nNew services or UI surfaces may be introduced without an architecture version change when they preserve these ownership boundaries. A new authority, truth store, runtime stage, connector ownership model, shared frontend authority or Governance bypass requires an explicit architecture version update.\n"}