{"slug":"architecture/PRODUCT_ARCHITECTURE_V1","title":"IntegrateWise — Final Product Architecture & System Spec","section":"architecture","sectionLabel":"Architecture","status":"superseded","type":"document","path":"architecture/PRODUCT_ARCHITECTURE_V1.mdx","bytes":18881,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Version:** 1.0.0  \n**Status:** SUPERSEDED — historical July 27 synthesis\n**Date:** July 27, 2026\n\n> Do not implement from this file. It contains superseded D1-truth, Triage\n> writer, Flow D and public naming claims. Current authority is\n> [`INTEGRATEWISE_ARCHITECTURE.md`](INTEGRATEWISE_ARCHITECTURE.md) v2.2 and\n> [`SPEC_AMENDMENTS_v1.md`](SPEC_AMENDMENTS_v1.md).\n\n---\n\n# 1. What IntegrateWise Is\n\n> **One workspace. One trust boundary. One Integration Manager. Everything else is a projection.**\n\nIntegrateWise is a **Continuity Platform** — not a dashboard, connector catalogue, AI chatbot, automation engine, memory provider, or CRM replacement.\n\n**Core doctrines:**\n\n- **Truth you own. AI you rent. Approval in between.**\n- **Normalize once. Render anywhere.**\n- **Models change. Memory does not.**\n\n---\n\n# 2. Canonical Naming\n\n| Concept                             | Responsibility                                                                |\n| ----------------------------------- | ----------------------------------------------------------------------------- |\n| **IntegrateWise**                   | Continuity Platform                                                           |\n| **Adaptive Spine / Digital Memory** | Canonical operational truth, context, lineage, relationships, governed memory |\n| **User Workbench**                  | Human-facing role/department/context-aware projection over the Spine          |\n| **Twin**                            | User-facing cognitive orchestrator — reads, reasons, explains, proposes       |\n| **Co-worker**                       | Operational role of the Twin — investigates, prepares, executes, verifies     |\n| **Triage Bot**                      | Intake classifier and governed canonical memory writer                        |\n| **Governance**                      | Policy evaluation, approval, authority, audit                                 |\n| **Capability Fabric**               | Discovers and resolves executable capabilities and adapters                   |\n| **Hermes**                          | Internal execution/orchestration runtime — NOT a second AI brain              |\n| **Continuity Fabric**               | Persistent schedules, events, retries, monitoring, reconciliation, closure    |\n| **Continuity Bridge**               | MCP/OAuth/API transport between external AI and IntegrateWise                 |\n| **IW-Spine-Network**                | External marketplace connector — user's entry point to IntegrateWise          |\n| **IW Spine Tools**                  | Semantic MCP/API tool surface exposed through IW-Spine-Network                |\n| **One Auth-to-Ecosystem**           | Identity, tenant, consent, scope bootstrap                                    |\n| **Integration Manager**             | External systems, connections, OAuth, webhooks, sync, connector health        |\n| **MCP Pool**                        | Customer Zero infrastructure only — not mandatory for tenants                 |\n| **Connector Marketplace**           | In-product discovery and activation of source systems                         |\n\n---\n\n# 3. V1 Infrastructure\n\n**Cloudflare-first product plane.**\n\n| Store               | Role                                                                            |\n| ------------------- | ------------------------------------------------------------------------------- |\n| **D1**              | Operational Spine, canonical active state                                       |\n| **KV**              | Hot context, cache, short-lived runtime state                                   |\n| **Durable Objects** | Session state, Twin working context, agent checkpoints, continuity coordination |\n| **R2**              | Raw payloads, files, evidence, archives                                         |\n| **Vectorize**       | Semantic retrieval index                                                        |\n| **Queues**          | Asynchronous pipelines                                                          |\n| **AI Gateway**      | Model/provider access                                                           |\n| **Neon Fortress**   | History, audit replication, recovery, analytics (outside hot path)              |\n\n---\n\n# 4. Complete System Flow\n\n```\nUser / External AI / Tool Marketplace / Workbench\n                    ↓\n        IW-Spine-Network / Bridge\n                    ↓\n         One Auth-to-Ecosystem\n                    ↓\n        Tenant + Workspace Resolution\n                    ↓\n           Integration Manager\n                    ↓\n    Connector / MCP / API / Webhook Fabric\n                    ↓\n                  LOAD\n                    ↓\n    CLASSIFY → NORMALIZE → RESOLVE → VALIDATE\n                    ↓\n            POLICY EVALUATION\n                    ↓\n           CANONICAL SPINE WRITE\n                    ↓\n       Entity 360 ←→ Memory / Knowledge\n                    ↓\n          Projection Engine\n                    ↓\n         Workbench / Twin Context\n                    ↓\n          Twin THINK / PROPOSE\n                    ↓\n         Governance / APPROVE\n                    ↓\n         Capability Resolver\n                    ↓\n      Hermes / Execution Runtime\n                    ↓\n         Source-System Action\n                    ↓\n       Verify and Reconcile\n                    ↓\n      Update Spine → Learn → Continue\n```\n\n**Frozen runtime sequence:** Enter → Authenticate → Resolve → Connect → Ingress → Load → Normalize → Store → Project → Think → Approve → Act → Repeat/Reconcile\n\n---\n\n# 5. Model Architecture (Model & Provider Agnostic)\n\n## 5.1 Model Pool\n\n| Alias             | Purpose                                     | Default                     |\n| ----------------- | ------------------------------------------- | --------------------------- |\n| `iw-fast`         | Classification, extraction, routing, Triage | Gemini 3.5 Flash-Lite       |\n| `iw-think`        | Twin reasoning, planning, proposals         | Gemini 3.6 Flash            |\n| `iw-deep`         | Complex reasoning, governance-sensitive     | GPT-5 Pro / Claude Opus 4.1 |\n| `iw-local-fast`   | Private/edge, fallback                      | GLM-4.7-Flash               |\n| `iw-local-reason` | Local reasoning, restricted egress          | gpt-oss-120b                |\n| `iw-embed`        | Knowledge indexing, semantic search         | Qwen3-Embedding-0.6B        |\n| `iw-rerank`       | Evidence ordering, memory ranking           | BGE Reranker                |\n| `iw-live`         | Realtime dialogue (deploy later)            | Gemini 3.1 Flash Live       |\n\n**Rule:** Aliases are the contract. Providers are pluggable. No agent, worker, or frontend references a provider name.\n\n## 5.2 Canonical Routing Policy\n\n```\nDeterministic sufficient? → No model\nClassification/extraction? → iw-fast\nNormal reasoning/planning? → iw-think\nComplex/consequential? → iw-deep + Governance\nSensitive data? → iw-local-reason\n```\n\n---\n\n# 6. Five Agentic Runtimes\n\n## 6.1 Twin Runtime\n\n**Role:** Cognitive orchestrator.\n\n```\nObserve → Orient → Reason → Explain → Plan → Propose → Monitor → Follow up\n```\n\n**May:** Answer, summarize, correlate, identify risks, draft, plan, recommend, propose, delegate, surface memory, follow up.\n\n**May NOT:** Approve own actions, execute directly, mutate Spine, promote memory, store credentials, own truth.\n\n**Model routing:** Normal → `iw-think`, Simple prep → `iw-fast`, Complex → `iw-deep`, Sensitive → `iw-local-reason`.\n\n## 6.2 Triage Agent\n\n**Role:** Sole governed cognitive and memory promotion path.\n\n```\nConversation / Agent output / Document / Execution outcome\n  → Triage\n  → Fact / decision / commitment / proposal / knowledge / noise\n  → Evidence + confidence\n  → Governance\n  → Promote / reject / retain\n```\n\n**Model routing:** Default `iw-fast`, Escalate `iw-think` for ambiguity/high value.\n\n## 6.3 Auto-Tuner\n\n**Role:** Adaptive workspace optimization.\n\n**Observes:** Entities opened, views used, fields edited/ignored, Twin requests, blocked work.\n\n**Proposes:** Navigation prioritization, field visibility, view ordering, grouping, contextual pages, capability placement, personal layouts.\n\n**Authority levels:**\n\n- Ambient ranking → automatic\n- Personal preference → automatic with undo\n- Shared workspace change → user/team confirmation\n- Structural change → Governance approval\n- Schema/policy change → never direct\n\n## 6.4 Connector/Schema Discovery Agent\n\n**Role:** Schema and capability discovery during installation.\n\n```\nDiscover → Recommend → Test → Human/governed approval → Publish mapping version → Replay\n```\n\n## 6.5 Verification/Reconciliation Agent\n\n**Role:** Post-execution verification.\n\n```\nApproved intent → Provider action → Re-ingestion → Comparison → Verification → Reconciliation → Closure\n```\n\n---\n\n# 7. Deterministic Services (No Models)\n\n| Service              | Role                                     |\n| -------------------- | ---------------------------------------- |\n| Gateway / TenantGate | Deterministic runtime                    |\n| Loader               | Deterministic writer                     |\n| Normalizer           | Deterministic transformation pipeline    |\n| Identity Resolution  | Deterministic-first with assisted review |\n| Projection Engine    | Deterministic composer                   |\n| Capability Resolver  | Deterministic registry + policy resolver |\n| Governance Engine    | Deterministic policy + authority engine  |\n| Hermes               | Execution coordinator                    |\n| Sync Engine          | Deterministic convergence runtime        |\n| Continuity Fabric    | Durable state machine + scheduler        |\n| Event Bus / Queues   | Infrastructure                           |\n| Model Router         | Intelligence infrastructure              |\n\n**Key boundary:** Hermes is NOT an AI agent. Projection Engine does NOT reason creatively.\n\n---\n\n# 8. Memory Architecture\n\n## 8.1 Memory Types\n\n| Type           | Purpose                                     |\n| -------------- | ------------------------------------------- |\n| Conversational | Raw AI/human conversational continuity      |\n| Working        | Short-lived active session/task context     |\n| Personal       | User-private approved preferences/patterns  |\n| Organizational | Approved shared facts, decisions, practices |\n| Entity         | Accumulated meaning per entity              |\n| Decision       | Decisions, rationale, authority, outcome    |\n| Signal         | Historical signals, responses, outcomes     |\n| Agent          | Agent checkpoints, outcomes, learning       |\n| Knowledge      | Documents, runbooks, policies, references   |\n\n## 8.2 Memory Lifecycle\n\n```\nRaw Conversation / Event\n  → Memory Intake\n  → Classification\n  → Candidate Memory\n  → Evidence Linking\n  → Review\n  → Promotion\n  → Personal / Organizational / Entity Memory\n  → Indexing\n  → Contextual Read\n  → Outcome Observation\n  → Future Candidate\n```\n\n**Rule:** Nothing becomes organizational memory immediately. Triage Bot is the canonical memory writer.\n\n---\n\n# 9. Data Flows\n\n## Flow A — Structured Operational Truth\n\n```\nConnector → Loader → Ingestion Queue → Normalizer → Identity Resolution\n  → Policy Evaluation → Spine Writer → Entity 360 → Signal Engine\n  → Twin Trigger → Proposal → Governance → Capability Execution\n  → Source Write-back → Re-ingestion → Reconciliation\n```\n\n## Flow B — Context and Knowledge\n\n```\nContext Source → Loader → Raw Payload Preservation → Parse and Classify\n  → Structured Metadata to Spine → Context Extraction → Knowledge Store\n  → Chunking + Embedding → Entity Linking → Entity360 Context\n```\n\n## Flow C — AI, Chat and Cognitive Output\n\n```\nAI Output / Chat → Conversational Buffer → Brainstorming Layer\n  → Memory Intake Queue → Triage Bot → Classification\n  → Candidate Memory/Knowledge/Proposal → Evidence + Confidence\n  → Governance / Human Review → Personal/Organizational Memory\n  → Re-index + Re-project\n```\n\n**Rule:** AI content never writes directly to the operational Spine.\n\n## Flow D — External AI and Tool Access\n\n```\nExternal AI / Tool / Agent\n  → IW-Spine-Network / Continuity Bridge\n  → One Auth-to-Ecosystem\n  → Tenant + Workspace Resolution\n  → IW Spine Tools (semantic surface)\n  → Context Package Assembly\n  → Twin / Capability Fabric\n  → Governance / Approval\n  → Capability Execution\n  → Outcome Verification\n  → Reconciliation\n  → Memory Update (via Triage)\n```\n\n**Rule:** External AI never accesses raw Spine. Only semantic tools and governed context packages.\n\n---\n\n# 10. Governance\n\n## 10.1 Authority Doctrine\n\n> **AI proposes. Human decides. The platform executes only after human approval.**\n\n## 10.2 Approval Lifecycle\n\n```\nDraft → Proposed → Awaiting Human Review → Approved/Rejected/Modified/Deferred\n  → Executing → Outcome Received → Verification Required → Verified\n  → Reconciled → Closed\n```\n\n## 10.3 Governance Decisions\n\n- Read-only allowed\n- Auto-approved low-risk\n- Human approval required\n- Additional evidence required\n- Step-up authentication required\n- Rejected\n- Blocked by policy\n\n---\n\n# 11. Platform Plane Components\n\n## Identity and Tenancy\n\nIdentity, Tenant, Workspace, Membership, RBAC, Consent, Session Policy\n\n## Configuration\n\nConfiguration Manager, Provider Management, Feature Flags, Schema Registry, Canonical Ontology\n\n## Integration\n\nIntegration Manager, Connector Registry, MCP Registry, Webhook Manager, Sync Manager, Connection Health, Secret References\n\n## Data\n\nLoader, Normalizer, Entity Resolution, Spine Writer, Adaptive Spine, Entity360, Projection Engine, Search, Fortress Replication\n\n## Memory and Knowledge\n\nConversational Intake, Triage Bot, Memory Promotion, Organizational Memory, Personal Memory, Agent Memory, Knowledge Platform, Vector Indexing\n\n## Intelligence\n\nTwin, Context Assembler, Signal Engine, AI Gateway, Model Router, Provider Adapters, Skills and Agents\n\n## Control and Execution\n\nGovernance, Approval Service, Capability Fabric, Continuity Fabric, Hermes Runtime, Workflow Engine, Scheduler, Notifications, Reconciliation\n\n## Platform Operations\n\nAudit, Observability, Usage and Cost, Billing, Admin APIs, Deployment Controls, Recovery, Support Operations\n\n---\n\n# 12. Product Plane\n\n**Owns:** Marketing, Signup, Onboarding, Activation Hub, Connector Marketplace, Workbench, Founder Ops, Twin Interaction, Knowledge/Memory surfaces, Promotion Queue, Approval Centre, Integration Status, Platform-admin projections.\n\n**Does NOT own:** Provider SDKs, Canonical database access, Raw secrets, Direct connector execution, Independent governance logic, Independent AI routing logic.\n\n---\n\n# 13. Acceptance Checklist\n\n## Activation\n\n- [ ] Marketplace user installs IW-Spine-Network\n- [ ] One Auth establishes tenant/workspace\n- [ ] Existing marketplace authorization reused\n- [ ] User connects one real source\n- [ ] Creamy Load produces useful context\n- [ ] Workbench displays value before deep hydration\n\n## Ingestion\n\n- [ ] Full/Delta/Webhook ingestion works\n- [ ] Duplicates do not duplicate canonical entities\n- [ ] Identity resolution works\n- [ ] Unresolved records enter quarantine\n\n## Schema Change\n\n- [ ] Drift detected\n- [ ] Unsafe writes pause/degrade\n- [ ] Mapping proposal reviewed\n- [ ] Approved version published\n- [ ] Quarantined records replay\n\n## Twin\n\n- [ ] Answers from authorized context\n- [ ] Evidence and confidence displayed\n- [ ] Different model can continue from same context\n- [ ] Cannot directly write to Spine\n\n## Memory\n\n- [ ] AI chat enters Brainstorming/Intake\n- [ ] Triage classification works\n- [ ] Candidate memory shows evidence\n- [ ] Approval promotes, rejection prevents\n- [ ] Promoted memory retrievable with scope\n- [ ] Origin and lineage visible\n\n## Governance\n\n- [ ] Proposal effects visible\n- [ ] Correct approval policy applied\n- [ ] Approval token scoped and expiring\n- [ ] Unauthorized actor cannot approve\n- [ ] Revoked authority blocks execution\n\n## Execution\n\n- [ ] Capability Resolver selects healthy adapter\n- [ ] Hermes executes idempotently\n- [ ] Native source IDs captured\n- [ ] Failure retries safely\n- [ ] Permanent failure enters dead-letter\n\n## Reconciliation\n\n- [ ] Source outcome verified\n- [ ] Outcome re-ingested\n- [ ] Spine reflects verified state\n- [ ] Projection refreshes\n- [ ] Audit agrees with source and Spine\n\n## Security\n\n- [ ] Cross-tenant reads fail\n- [ ] Raw credentials never reach frontend or AI\n- [ ] Revoked connectors disable scheduled work\n- [ ] Audit records available\n\n---\n\n# 14. Prohibited Directions\n\n1. Do not redesign platform for every new connector\n2. Do not publish internal subsystems as separate marketplace products\n3. Do not turn Hermes into user-facing Twin\n4. Do not let Twin execute directly\n5. Do not let AI output directly mutate Spine\n6. Do not treat every chat message as organizational memory\n7. Do not let Workbench store independent truth\n8. Do not expose raw database/infrastructure publicly\n9. Do not require re-authorization when delegation exists\n10. Do not enable write-back by default\n11. Do not put raw credentials in schemas/MCP/capability definitions\n12. Do not make Schema AI part of deterministic hot path\n13. Do not treat Vectorize/KV/DOs as truth stores\n14. Do not expose Customer Zero MCP Pool as mandatory tenant concept\n15. Do not wait for complete hydration before showing value\n16. Do not expand architecture before Customer Zero demonstrates complete path\n\n---\n\n# 15. Final Definition\n\n```\nOne Auth-to-Ecosystem\n+ Integration Manager\n+ Connector and MCP Fabric\n+ AI Loader\n+ Normalizer\n+ Adaptive Spine\n+ Digital Memory\n+ Knowledge Platform\n+ Entity360 and Projection Engine\n+ Signal and Intelligence Engine\n+ Twin\n+ Triage Bot\n+ Governance\n+ Capability Fabric\n+ Hermes Execution Runtime\n+ Continuity Fabric\n+ IW-Spine-Network\n+ IW Spine Tools\n+ Adaptive User Workbench\n+ Activation Hub\n+ Platform Operations\n```\n\n**Operating loop:**\n\n```\nConnect once → Load reality → Normalize into shared truth\n→ Preserve context and memory → Project right work to each user\n→ Let Twin reason with evidence → Let Governance decide authority\n→ Let Capability Fabric resolve execution → Let Hermes perform approved work\n→ Verify source outcome → Reconcile Spine → Learn through governed memory\n→ Continue until loop is closed\n```\n\n> **One Auth establishes the ecosystem relationship. Digital Memory preserves context. Twin reasons. Governance authorizes. Capability Fabric executes. Continuity Fabric keeps work alive until source, Spine, and audit record are reconciled.**\n"}