{"slug":"architecture/CANONICAL_ARCHITECTURE_V4","title":"Canonical Architecture v4.1.0","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/CANONICAL_ARCHITECTURE_V4.mdx","bytes":4719,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Status: SUPERSEDED ARCHITECTURE LINEAGE.** D1-as-canonical, direct primitive\n> coupling and any conflicts in this file must not be implemented. Current\n> authority is [`INTEGRATEWISE_ARCHITECTURE.md`](INTEGRATEWISE_ARCHITECTURE.md) v2.2,\n> subject to [`SPEC_AMENDMENTS_v1.md`](SPEC_AMENDMENTS_v1.md).\n\nOriginal status: CURRENT\nScope: IntegrateWise runtime boundaries, communication hierarchy, capability/execution/sync separation\nCanonical Owner: IntegrateWise Platform\nLast Verified: 2026-07-20\nEvidence Basis: Product doctrine v4.1.0, existing Gateway/Spine code, Cloudflare runtime substrate\n\n## 1. CORE PRINCIPLE\n\nThe Spine is the canonical runtime substrate. Internal communication must not be implemented as a chain of HTTP microservice calls. Cloudflare Workers, D1, KV, R2, Queues, and Durable Objects are first-class primitives; use them directly.\n\n## 2. COMMUNICATION HIERARCHY\n\n| Priority | Mechanism                | Use When                                                        |\n| -------- | ------------------------ | --------------------------------------------------------------- |\n| 1        | In-process function call | Logic lives in the same Worker/module                           |\n| 2        | Repository access        | Reading/writing shared state (D1/KV/R2/DO)                      |\n| 3        | Service binding          | Invoking another Worker that owns a distinct runtime capability |\n| 4        | Queue                    | Background or long-running work, retries, async propagation     |\n| 5        | External HTTP            | Browser ↔ Gateway, SaaS APIs, webhooks, public APIs only        |\n\nAnti-pattern: chaining internal APIs through HTTP for operations that could use repositories or service bindings.\n\n## 3. RUNTIME LAYERS\n\n```text\nUser\n  │\n  ▼\nProjection              ← UI never consumes raw API responses\n  │\n  ▼\nCapability Layer        ← declarative: what can be done\n  │\n  ▼\nExecution Layer         ← imperative: how it is performed, governed, committed\n  │\n  ▼\nSync Layer              ← async: how the rest of the world converges\n  │\n  ▼\nSpine / Memory / Intelligence / Governance\n```\n\n### 3.1 Capability Layer\n\nCapabilities are declarative contracts. They declare:\n\n- Input/output shapes\n- Required permissions/scopes\n- Policy requirements\n- Approval requirements\n- UI metadata\n- Audit requirements\n\nThey do not implement execution logic.\n\n### 3.2 Execution Layer\n\nExecution is the runtime. When a capability is invoked:\n\n1. Validate intent and inputs\n2. Load context\n3. Run governance gates\n4. Execute steps\n5. Emit events\n6. Return result\n\nExecution commits canonical state first. Sync is independent.\n\n### 3.3 Sync Layer\n\nSync detects committed changes and propagates them to external/internal targets asynchronously. Failures in sync do not invalidate successful execution.\n\n## 4. GOVERNANCE: TWO-GATE MODEL\n\n```text\nCapability Invocation\n  │\n  ▼\nGate 1: Pre-Proposal Evaluation\n  - role/scopes/allowlists/denylists\n  - Output: ALLOW_PROCEED | DENY | REQUIRE_PRE_APPROVAL\n  │\n  ▼\nTwin Processing / Execution Plan Generation\n  │\n  ▼\nGate 2: Post-Proposal Evaluation\n  - risk scoring, evidence linking, confidence floors\n  - Output: AUTO_APPROVE | REQUIRE_HUMAN_APPROVAL | DENY\n```\n\nBoth gates are enforced in the Execution Layer. The UI only emits intent.\n\n## 5. UI BOUNDARY\n\n```text\nUser\n  │\n  ▼\nGateway API           ← only HTTP boundary the UI crosses\n  │\n  ▼\nProjection Layer     ← stable contract consumed by React\n  │\n  ▼\nCapability/Execution/Sync\n```\n\nRules:\n\n- UI components must not call raw databases\n- UI components must not bypass the Gateway for mutations\n- Projections must be swappable by changing the adapter, not the component\n\n## 6. EVENT FLOW\n\n```text\nCapability\n  │\n  ▼\nExecution\n  │\n  ▼\nSpine Commit\n  │\n  ▼\nEvent Bus\n  ├── Sync Engine\n  ├── Projection Engine\n  ├── Intelligence Engine\n  ├── Notification Engine\n  ├── Automation Engine\n  └── Analytics Engine\n```\n\nEverything after Spine commit is event-driven.\n\n## 7. IMPLEMENTATION BOUNDARIES IN REPO\n\n- Gateway: orchestration, auth, routing, capability registry front-door\n- Spine: canonical state in D1 + KV + DO primitives\n- Pipeline: ingress/normalization/staging path\n- Web app: projection consumers only; no direct infra imports\n\n## 8. MIGRATION RULES\n\n- Do not introduce new public HTTP routes between internal Workers without explicit naming\n- Prefer adding modules under `services/gateway/src/{capabilities,execution,sync}` over expanding `workspace-spine.ts`\n- UI changes must go through projection contracts in `apps/web/src/projections/`\n"}