Unclassified

IntegrateWise Architecture v2.2

Status: CANONICAL
Date: 2026-08-11
Supersedes: previous architecture locks, consolidated contracts and canonical/final architecture framings where they conflict.

1. Product statement

IntegrateWise is an Operational Continuity Platform. It preserves governed business context across systems, humans, models and agents while keeping execution bounded by explicit authority.

The surface/product boundary is:

One Auth → User Workbench → contextual Twin → Tool Capabilities

The platform underneath is:

Product Package + Platform Backend + Governed Spine + Execution Runtime

2. System boundary

HOST
identity + connected apps + connector authority
  ↓
ONE AUTH
ecosystem entry + session/tenant/delegation binding
  ↓
PRODUCT PACKAGE
Discovery + Capabilities + Spine Cache + ADK + Orchestrator
+ Business Context + Loader + Normalizer + MCP Connector + Tool Capability
  ↓
FRONTEND RUNTIME
shared Auth + Connectors + MCP + Platform context
+ frontend-owned domain/product projection
  ↓
USER WORKBENCH / OTHER FRONTENDS
phase/lifecycle projection + continuity + Twin + Execution Mode
  ↓
PLATFORM BACKEND
Package Control Plane + Services + AI + Agents + Memory + Pipelines
  ↓
GOVERNED EXECUTION
Governance → orchestrated execution/Hermes → provider → reconciliation

3. Ownership matrix

Concern	Owner	Must not own
Host identity	Host / One Auth trust boundary	Provider business data truth
Provider credentials	Host connector authority / approved credential vault	Workbench, agents, Twin, projection records
Connector projection	IntegrateWise projection registry	Raw provider refresh tokens
Canonical business truth	Business Context / governed Spine writers	Memory, UI state, agents
Operational cache	Spine Cache / D1/KV	Irreplaceable canonical history
Memory	Platform Memory	Canonical operational truth
Frontend shared runtime	Auth + Connector + MCP + Platform services	Domain-specific UI ownership
Domain frontend	Domain/product UX and projection composition	Separate identity, connector, MCP or platform truth
Workbench composition	Projection Engine	Provider credentials or canonical writes
Capability contract	Capability Manager / registry	Policy bypass
Execution authority	Governance	Model confidence
Execution coordination	Orchestrator / Hermes	Approval policy ownership
Outcome reconciliation	Sync/Pipeline/Spine promotion	Client-side optimistic truth

4. One Auth

One 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.

A 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.

5. Product Package

Each Product Package composes ten responsibilities:

Discovery — packages, connector projections, schemas, MCP endpoints, capabilities, versions and health.
Capabilities — typed/versioned effective operations available to the current principal/context.
Spine Cache — rebuildable, freshness-aware materialized operational state.
ADK — stable runtime/developer kernel for context, capability invocation, lifecycle, policy hooks and telemetry.
Orchestrator — durable workflows, retries, compensation, approvals, tools, services and bounded agent tasks.
Business Context — canonical semantic entities, relationships, assertions, provenance, temporal validity and policy metadata.
Loader — extraction, pagination, webhooks, cursors, raw envelopes, checkpoints and replay.
Normalizer — provider-to-canonical mapping, validation, deduplication, identity resolution and lineage.
MCP Connector — governed MCP exposure/consumption and protocol translation.
Tool Capability — typed executable operation with schema, side-effect class, policy, idempotency, version and audit contract.

6. Shared frontend architecture

Every IntegrateWise frontend shares the same four platform capabilities:

Auth + Connectors + MCP + Platform

The rest of the frontend may be independently owned.

Frontend
├── Shared Auth
├── Shared Connectors
├── Shared MCP
├── Shared Platform access
└── Frontend-owned domain/product UX and projections

A 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.

Replacing a frontend must not require users to reauthenticate into a new ecosystem identity, reconnect provider accounts, redefine MCP capabilities or migrate Platform Backend truth.

See SHARED_FRONTEND_SHELL_AND_DOMAIN_OWNERSHIP.md.

7. User Workbench and frontend projections

There 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.

The frontend is projection-based:

backend canonical tables
+ relationships
+ lifecycle / phase
+ continuity
+ tenant / RBAC
+ connector availability
+ Tool Capability availability
→ Projection Engine
→ frontend view

Every frontend route must identify its lifecycle, phase, primary backend tables, supporting tables/relationships, continuity inputs, filters, projected capabilities, write path and rehydration trigger.

The 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.

See LIFECYCLE_CONTINUITY_AND_PROJECTION_MAP.md.

8. Lifecycle, phases and continuity

User flow and execution are phase-, lifecycle- and continuity-driven rather than page-first.

The generic operating loop is:

Resume
→ Orient
→ Decide
→ Govern
→ Execute
→ Reconcile
→ Transition
→ Continue

A 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.

Capability availability is phase-aware:

entity + lifecycle_stage + phase
+ connector/capability availability
+ tenant policy + RBAC
→ available Tool Capabilities

A connector's technical capability alone is insufficient to expose an action. The action must be valid for the current business lifecycle phase.

9. Execution Mode

Every capability invocation follows:

select capability
→ bind entity/subdomain + lifecycle/phase context
→ validate schema, connector availability and policy inputs
→ optional dry-run
→ Governance
   ├─ allowed
   ├─ approval_required
   └─ blocked
→ execute when authorized
→ structured result
→ telemetry + evidence + audit
→ reconciliation
→ lifecycle transition when validated
→ continuity update
→ outcome promotion
→ projection rehydrate

Governance is always mandatory. Approval is conditional on policy.

allowed: explicitly pre-authorized, narrowly bounded execution.
approval_required: proposal must receive a scoped human approval artifact before execution.
blocked: execution denied.

Consequential external mutations should default to approval_required.

10. Platform Backend

Platform Backend consists of:

Package Control Plane
Services
AI
Agents
Memory
Pipelines

The Platform Management Console configures and operates these capabilities. It is distinct from the User Workbench and other product/domain frontends.

11. Platform Management Console

Canonical modules:

Integration Manager
Connector Marketplace
Activation Hub
Capability Manager
MCP Pool
AI Models
Knowledge
Memory & Continuity
Automation
Pipelines
Governance
Observability
Administration
- Organizations
- Users
- Roles
- Permissions
- Audit
- Billing
- Deployments
- API Keys
- Security

Connector-aware routing is a hard constraint across Configuration, Activation, Integration, Discovery and Schema flows.

12. Truth and storage

Canonical governed business truth belongs in Neon/Postgres through approved writers/pipelines.
Durable business entity families belong in semantic tenant-scoped backend tables.
Frontend destinations are projections; do not create page-shaped truth tables solely for UI convenience.
D1/KV may hold bounded, reconstructable operational state and Spine Cache materializations.
Object storage may hold evidence bytes while canonical metadata/lineage remains governed.
Memory is subordinate to canonical business truth.
AI/model outputs are candidates/proposals until governed promotion.

13. Runtime sequence

Host identity/grants
→ One Auth
→ Discovery
→ connector projections
→ Loader
→ Normalizer
→ Business Context / Spine promotion
→ Spine Cache
→ lifecycle + continuity composition
→ Projection Engine
→ shared frontend runtime (Auth + Connectors + MCP + Platform)
→ frontend-owned projection
→ Twin/user intent
→ phase-valid Tool Capability
→ Governance
→ Orchestrator/Hermes
→ provider/internal service
→ Sync/reconciliation
→ lifecycle transition
→ continuity/timeline update
→ outcome promotion
→ refreshed projection

14. Invariants

One Auth is the ecosystem entry.
Host connector authority is not duplicated.
Connector projections never contain copied provider secrets.
Every frontend shares Auth + Connectors + MCP + Platform runtime capabilities.
Domain/product frontends may own the remaining UX and projection composition.
Replacing a frontend must not require migrating identity, connectors, MCP definitions or Platform Backend truth.
Frontends project backend canonical tables; they do not own independent business truth.
Every frontend route has a backend table/projection map.
User flow and execution are lifecycle-, phase- and continuity-driven.
Twin is contextual and non-authoritative.
Business Context/Spine owns canonical business truth.
Memory does not silently become truth.
Tool Capabilities are first-class executable contracts.
Capability availability is phase-aware, connector-aware and policy-aware.
Every execution passes Governance.
approval_required requires a scoped human approval artifact.
allowed is explicit policy, not a bypass.
Agents/models do not directly own provider credentials or canonical write authority.
Outcomes are reconciled before becoming canonical.
Reconciliation may drive validated lifecycle transition and continuity update.
Connector-aware routing is mandatory across lifecycle/configuration flows.
Public/client surfaces do not own provider credentials or canonical workflow truth.
Generated/public documentation never overrides source documentation.

15. Environment promotion

The same versioned artifacts progress through:

Development → Customer Zero → Customer Production

Only code, packages, schemas, manifests, policies/defaults and versioned configuration definitions move forward. Tenant data, secrets, runtime caches, queues, evidence and audit records do not.

16. Change policy

New 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.