{"slug":"internal/architecture/INTEGRATEWISE_SYSTEM_OVERVIEW","title":"IntegrateWise — Whole System Overview","section":"internal","sectionLabel":"Internal","status":"unclassified","type":"document","path":"internal/architecture/INTEGRATEWISE_SYSTEM_OVERVIEW.mdx","bytes":29297,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> Canonical internal reference for the whole IntegrateWise system.\n> Descriptive first-read document for team members, operators, builders, and internal documentation consumers.\n> **Architecture reference:** See `docs/ARCHITECTURE_CANONICAL.md` for the locked canonical architecture (May 28, 2026).\n\n---\n\n## Document Identity\n\n- Document family: Whole-system internal reference\n- Audience: internal team, operators, builders, reviewers, new contributors\n- Purpose: explain the full IntegrateWise system in one place before readers go deeper into product, architecture, operations, design, playbooks, or runbooks\n- Canonical stance: descriptive, cross-cutting, system-wide\n- Reading rule: use this page first, then branch into specialized docs\n\n### Canonical statement\n\nIntegrateWise is a continuity-native operating environment over the Adaptive Spine.\nIt connects external systems into structured truth, linked context, governed AI memory, and controlled action.\n\nEvery user works in the **Operational Workbench** — the primary surface where projected truth is shown and work happens. The Twin is embedded as a collapsible sidebar that surfaces insights and requests approvals only when needed. The **Twin Workbench** is the full AI environment (OpenWebUI-style: skills, knowledge, agents, prompts, conversational library). The **Memory View** is a documentation-site-style surface for browsing and managing org, personal, and conversational memory.\n\nBusiness Operations is a department with its own views — 14 modules, cross-department rollup, founder/CEO/COO/CTO lenses. Every other department (Sales, CS, Finance, etc.) has its own domain workbench. BizOps is the cross-cutting view over all of them.\n\nHermes and Claw are the runtime agents that power the system. Their features — skill execution, proposal routing, execution logs, agent colony — are surfaced inside the product, not external to it.\n\n### What this document is not\n\nThis document is not:\n\n- a public-facing product page\n- a runbook\n- a feature checklist\n- a live-status board\n- a single-service implementation spec\n\nIt is the internal descriptive map of the whole system.\n\n---\n\n## 1. What the System Is\n\nIntegrateWise exists to solve a compound organizational problem:\n\n- business truth is scattered across too many tools\n- context is buried in conversations, documents, and operational traces\n- AI systems are often asked to reason without real organizational grounding\n- automation is risky when governance is weak or invisible\n\nIntegrateWise addresses this by creating one governed system with four essential properties:\n\n1. truth is normalized and structured into the Spine\n2. context is linked to entities and operational situations\n3. AI memory compounds through review and approval rather than silent auto-write\n4. execution remains governed, traceable, and reversible\n\nThe result is not just another dashboard, assistant, or integration layer.\nIt is a work-and-governance system where context, intelligence, and action stay connected.\n\n---\n\n## 2. Canonical Boundary Rules\n\nThe whole system should be read through these boundary rules:\n\n- **Operational Workbench** = the primary surface where every user works. Left sidebar navigation. Twin sidebar pops out only when needed (insights, approvals, action execution).\n- **Twin Workbench** = full AI ecosystem surface — skills, knowledge, agents, prompts, conversational library. OpenWebUI-style. Can be positioned at different locations in the shell.\n- **Memory View** = documentation-site style surface for browsing personal, organizational, and conversational memory. Can be positioned at different locations.\n- **Business Operations** = a department with its own views (14 modules, cross-department rollup, founder/CEO/COO/CTO lenses) — not a separate product, a domain workbench like CS or Sales but cross-cutting.\n- **Governance is embedded** — not a separate workbench. Approval panels appear inline in the Operational Workbench via the Twin sidebar.\n- **Hermes and Claw are internal** — their runtime features (skill execution, proposal routing, execution logs, agent colony) are surfaced inside the product.\n- Loader and Normalizer are internal stages of the MCP pipeline, not alternatives to MCP.\n- MCP is the Spine gateway, not a list of tool wrappers.\n- AI does not directly mutate canonical context without governance.\n- Flow C memory does not silently become Spine context.\n- Triage Bot is the sole writer to memory — no AI, no user writes directly.\n\nThese boundaries are load-bearing. Most documentation drift comes from collapsing them.\n\n---\n\n## 3. Whole-System Map\n\n```text\nExternal Systems\n(CRM, billing, support, docs, chat, files, calendars, AI sessions)\n        |\n        v\nConnectors / Watchers / AI Connectors\n        |\n        v\nMCP Pipeline: Loader -> Normalizer -> Spine + Context + Memory Stores\n        |                                        |\n        |                                        v\n        |                                  Entity 360\n        |                                        |\n        +----------------------------+-----------+----------------------------+\n                                     |                                        |\n                                     v                                        v\n                      Operational Workbench                          Twin Workbench\n                  (left sidebar nav; Twin sidebar              (skills, knowledge, agents,\n                   pops out when needed)                        prompts, conv. library)\n                                     |                                        |\n                                     +-------------------+--------------------+\n                                                         |\n                                                         v\n                                                    Memory View\n                                      (personal + org + conversational memory,\n                                       documentation-site style)\n                                                         |\n                                                         v\n                                    Governance (embedded at every layer)\n                                    Approval inline → Hermes/Claw execute\n                                                         |\n                                                         v\n                                                 Act / Workflows\n                                                  / external write\n                                                         |\n                                                         v\n                                                 Repeat loop on Flow A\n```\n\n### Reading this map correctly\n\n- external systems remain external systems; IntegrateWise does not require a wholesale tool replacement thesis\n- the Spine is the governed truth substrate, not a marketing abstraction\n- Entity 360 is the convergence point for truth, context, governed memory, and signals\n- the three surfaces are different projections over one system, not three unrelated products\n- governance is not a surface — it is embedded at every layer; approval panels appear inline\n- Hermes and Claw are internal — their runtime features are surfaced inside the product\n- only structured action results re-enter the continuous repeat loop\n\n---\n\n## 4. The Three Surfaces\n\n| Surface               | Primary role                                                                   | Primary user posture                     | Reads from                                         | Writes through                                 |\n| --------------------- | ------------------------------------------------------------------------------ | ---------------------------------------- | -------------------------------------------------- | ---------------------------------------------- |\n| Operational Workbench | primary work surface; left sidebar nav; Twin sidebar pops out when needed      | operate, review, manage, decide, approve | Spine truth, projections, context, signals         | Gateway / governed APIs                        |\n| Twin Workbench        | full AI ecosystem surface — skills, knowledge, agents, prompts, conv. library  | ask, inspect, synthesize, reason, plan   | Entity 360, knowledge, evidence, tools, MCP        | governed proposal paths, memory via Triage Bot |\n| Memory View           | personal, organizational, and conversational memory — documentation-site style | browse, review, promote, connect         | personal_memory, org_memory, conversational_memory | governed promotion, user connectors            |\n\n### Operational Workbench\n\nThe Operational Workbench is where every user spends the majority of their time.\nLeft sidebar navigation. Domain-specific views (BizOps, Account Success, Sales, Finance, etc.).\nThe Twin sidebar is collapsible — it pops out only when needed to surface insights, request approvals, or execute actions. It does not occupy permanent screen space.\nBusiness Operations is a department within the Operational Workbench — 14 modules, cross-department rollup, founder/CEO/COO/CTO lenses.\n\n### Twin Workbench\n\nThe Twin Workbench is the full AI ecosystem surface — OpenWebUI-style.\nSkills, Knowledge, Import functions, Agents, Prompts, Conversational Library.\nThis is where the system reasons, retrieves, explains, shows evidence, invokes tools, and helps humans navigate full-context questions and action proposals.\nConversational memory lives here.\nCan be positioned at different locations in the shell.\n\n### Memory View\n\nThe Memory View surfaces personal, organizational, and conversational memory in a documentation-site style.\nUsers browse, review, and promote memory through this surface.\nCan be positioned at different locations in the shell.\nPersonal and Organizational Memory are also surfacable through user-owned connectors.\n\n### Governance\n\nGovernance is not a surface. It is embedded at every layer.\nApproval panels appear inline in the Operational Workbench via the Twin sidebar — not in a separate screen.\nEvery action has lineage, every decision is recorded, approval gates exist before execution.\n\n---\n\n## 5. The Core Operating Loop\n\nThe system is best understood through its operating loop:\n\n```text\nLoad -> Store -> Think -> Govern -> Act -> Repeat -> Adjust\n```\n\n### Meaning of each stage\n\n- Load: connectors and loaders collect data from source systems\n- Store: pipeline and normalization write structured truth and linked context into the governed system\n- Think: the Twin reasons over Entity 360, evidence, and governed memory\n- Govern: approvals, policy checks, HITL control, and audit conditions are applied\n- Act: approved actions execute on external systems or internal controlled surfaces\n- Repeat: structured consequences re-enter Flow A and become fresh operational truth\n- Adjust: the system improves through approved memory, feedback, and audit-trace learning\n\n### Critical loop rule\n\nRepeat applies to structured operational data.\nIt does not apply to Flow B as a loop.\nIt does not apply to Flow C as silent truth mutation.\n\n---\n\n## 6. The Three Data Flows\n\n| Flow   | What enters                      | Primary source examples                       | Primary writer(s)                      | Primary destination                                       | Repeat loop | Approval requirement                                   |\n| ------ | -------------------------------- | --------------------------------------------- | -------------------------------------- | --------------------------------------------------------- | ----------- | ------------------------------------------------------ |\n| Flow A | structured truth                 | CRM, billing, support, product, finance tools | connector + loader + normalizer        | Spine truth and department-routed tables                  | yes         | required before consequential write-back               |\n| Flow B | linked context                   | email, docs, chat, meetings, files            | connector + loader + knowledge service | context_extractions and linked entity context             | no          | not for ingest; governance matters when used in action |\n| Flow C | AI memory and governed knowledge | Twin reasoning, AI sessions, agent outputs    | Triage Bot + memory consolidator       | ai_memories -> consolidated_memories / approved knowledge | no          | yes, for approval and promotion                        |\n\n### Flow A — Structured Truth\n\nFlow A is the repeat-loop backbone of the system.\nIt is where records from external tools become normalized truth inside the governed substrate.\nIf an approved action updates an external record, that change re-enters Flow A and becomes part of the new business state.\n\n### Flow B — Context\n\nFlow B captures the human layer around the business.\nThis includes messages, notes, documents, meeting traces, and content that explains why structured state looks the way it does.\nContext is not noise; it is the meaning layer that makes AI reasoning operationally useful.\n\n### Flow C — Governed AI Memory\n\nFlow C exists so that AI-generated memory is never treated as raw truth just because it was generated.\nThe Triage Bot is the gatekeeper.\nMemory proposals are reviewed, approved, and consolidated into governed knowledge before they can be treated as part of the working intelligence substrate.\n\n---\n\n## 7. Entity 360 and the Convergence Layer\n\nEntity 360 is where the system becomes operationally legible.\nIt is not a cosmetic feature.\nIt is the read-time assembly layer that brings together:\n\n- structured truth\n- linked context\n- governed memory\n- active signals\n- evidence chains\n\n### Why Entity 360 matters\n\nWithout Entity 360, the system remains a collection of ingestion paths and surface claims.\nWith Entity 360, the system becomes a usable reasoning substrate.\nIt gives both humans and the Twin a single converged reference point per entity, account, task, situation, or operational object.\n\n### Entity 360 rule\n\nEntity 360 is a convergence and read surface.\nIt should not be mistaken for an uncontrolled direct-write surface.\n\n---\n\n## 8. Storage and Runtime Planes\n\nThe whole system spans multiple storage and runtime planes. They do different jobs.\n\n### 8.1 Spine DB — canonical context plane\n\nSpine DB is the primary canonical data plane for structured context, governance state, approved knowledge records, and realtime app reads.\nIt is where the system expects the durable business state to live.\n\n### 8.2 Cloudflare operational plane\n\nCloudflare Workers, Queues, KV, D1, R2, and Durable Objects support the operational runtime.\nThis plane handles:\n\n- queue-based processing\n- edge coordination\n- caching\n- dedup support\n- operational buffering\n- realtime coordination\n- service composition and API routing\n\n### 8.3 External operating systems and tools\n\nExternal tools remain important.\nIntegrateWise is designed to read from them, reason across them, and write back to them through governed channels where appropriate.\nThey are part of the operating surface of the customer, not noise to ignore.\n\n### 8.4 Documentation and knowledge surfaces\n\nBookStack, Coda, Notion, AFFiNE, and similar systems may serve as external operating or publishing surfaces.\nInternal documentation can and should describe them as part of the total system where they matter.\n\n---\n\n## 9. Canonical Data Objects and Tables\n\nThe table below is a documentation-level system map.\nIt is meant for internal orientation, not as a substitute for schema files or migrations.\n\n| Object / table           | Purpose                                                  | Primary writer               | Primary readers                           | Runtime note                                      |\n| ------------------------ | -------------------------------------------------------- | ---------------------------- | ----------------------------------------- | ------------------------------------------------- |\n| tenant_spine_config      | tenant schema activation and downstream shaping          | onboarding                   | loader, normalizer, projections           | canonical object                                  |\n| connectors               | connector installation state, auth status, sync metadata | connector layer              | app, operators, health views              | runtime-backed                                    |\n| spine.entities           | central structured entity truth                          | normalizer                   | app, Entity 360, Twin                     | canonical object                                  |\n| department-routed tables | domain-specific structured truth by department/schema    | normalizer                   | app, projections, Entity 360              | canonical object                                  |\n| context_extractions      | linked context artifacts and extracted references        | knowledge service            | app, Entity 360, Twin                     | canonical object                                  |\n| signals                  | Twin or reasoning-derived active signals                 | think service                | app, Twin, operational views              | canonical object                                  |\n| actions                  | governed action queue / action state                     | workflow / govern / act path | app, governance, operators                | runtime-backed                                    |\n| ai_memories              | memory proposals and pre-consolidation state             | Triage Bot                   | knowledge workflows, operators            | canonical object                                  |\n| consolidated_memories    | approved and consolidated knowledge memory               | memory consolidator          | app, Entity 360, Twin, approved retrieval | canonical object                                  |\n| governance_audit_log     | audit trail for governed decisions and mutation          | govern path                  | governance, operators                     | canonical object                                  |\n| normalization_errors     | pipeline failures, replay and review candidates          | DLQ / failure consumers      | operators                                 | canonical object                                  |\n| governance_policies      | persistent governance policy state                       | governance management        | govern runtime                            | pending migration / runtime gap noted in ops docs |\n| governance_rules         | persistent rule set for approval decisions               | governance management        | govern runtime                            | pending migration / runtime gap noted in ops docs |\n| spine_blocks             | hard stop / block records for protected flows            | governance control plane     | govern/runtime observers                  | pending migration / runtime gap noted in ops docs |\n| twin_insights            | explicit Twin output record store where used             | think/twin side              | app/governance                            | pending migration / runtime gap noted in ops docs |\n\n### How to read this table\n\n- canonical object = part of the intended stable whole-system model\n- runtime-backed = known to exist in current runtime materials or operational mirrors\n- pending migration = documented in local runtime-state material as expected by code but not consistently present yet\n\n---\n\n## 10. Internal Table Views and Reporting Views\n\nInternal docs are allowed to contain descriptive table views.\nThese views can exist as:\n\n- SQL views\n- Spine DB views\n- Coda tables\n- internal dashboards\n- operational reporting surfaces\n\nWhat matters is that the view is semantically correct and clearly named.\n\n### Recommended canonical internal views\n\n| View                       | Purpose                                                                         | Backed by                                                              | Status                            |\n| -------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------- |\n| v_entity_360_summary       | one-row operational summary per entity with truth, context, memory, and signals | spine.entities + context_extractions + consolidated_memories + signals | canonical internal reporting view |\n| v_connector_health         | connector auth, freshness, sync status, failure pressure                        | connectors + operational status feeds                                  | canonical internal reporting view |\n| v_tenant_schema_activation | tenant, department, industry, active schema and surface state                   | tenant_spine_config + tenant/onboarding state                          | canonical internal reporting view |\n| v_normalization_quality    | pipeline quality, failures, stage pressure, DLQ load                            | normalization_errors + pipeline stats                                  | canonical internal reporting view |\n| v_memory_pipeline          | pending memory, approved memory, consolidation freshness, review load           | ai_memories + consolidated_memories                                    | canonical internal reporting view |\n| v_governance_queue         | proposals awaiting approval with policy and consequence context                 | actions + governance state                                             | canonical internal reporting view |\n| v_action_feedback_loop     | approved actions and whether their consequences reappeared in structured truth  | actions + structured follow-through                                    | canonical internal reporting view |\n| v_signal_feed              | active evidence-backed signals by entity, severity, freshness, domain           | signals + linked entity state                                          | canonical internal reporting view |\n| v_surface_access_map       | which tenant/users have which surfaces, layers, and access patterns enabled     | tenant configuration + role/surface state                              | canonical internal reporting view |\n\nThese views are valid documentation objects even before every one of them exists as a physical SQL view.\nThey are part of the internal language of the system.\n\n---\n\n## 11. Runtime Components and Services\n\n| Layer               | Component group                                             | Role in the whole system                                                |\n| ------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------- |\n| Connection          | connectors, watchers, AI connectors, webhook ingestion      | bring source-system data into the governed pipeline                     |\n| MCP Pipeline        | MCP boundary → Loader (fetch) → Normalizer (transform)      | protocol-level ingestion; Loader and Normalizer are internal MCP stages |\n| Processing          | knowledge processing, identity logic                        | embed, deduplicate, link, route                                         |\n| Truth and context   | Spine, context stores, entity model                         | hold the operational model the rest of the system reasons over          |\n| Cognition           | think service, Twin, prompts, tools, MCP                    | reason, retrieve, explain, propose                                      |\n| Governance          | govern service, Triage Bot, approvals, audit, policy checks | stop uncontrolled execution; Triage Bot is sole memory writer           |\n| Action              | act service, workflows, agentic claw handoff                | hand off approved action to user's own stack for execution              |\n| Operational runtime | gateway, Cloudflare queues/KV/D1/R2/DOs                     | routing, cache, coordination, buffering, edge execution                 |\n\n### Workflow execution (Cloudflare Workflows)\n\nCloudflare Workflows + Queues are the workflow and execution fabric of IntegrateWise\n(`services/workflow`). n8n is NOT used as IntegrateWise infrastructure — it is only ever\na customer-owned tool that the Twin may hand a playbook to, or whose run traces the\nworkbench absorbs for visibility.\nIt matters because governed execution should remain visible and orchestrated rather\nthan hidden inside ad-hoc tool actions.\n\n---\n\n## 12. Current Runtime Indicators\n\nThis section exists so internal readers do not confuse doctrine with live status.\nThese are indicators, not the final architectural truth.\n\n### Runtime state (May 2026)\n\n- 22+ CF Workers deployed\n- IntegrateWise MCP = connected (20 tools)\n- Cloudflare Workflows/Queues = live (services/workflow)\n- Hermes Agent = connected\n- Active Memory Layer = live on Cloudflare (D1, KV, AI Search) with Supabase (memory.\\* schema) as the Fortress backup\n- CouchDB = removed permanently\n\n### Runtime-state references\n\nFor deeper live-state or historical operational interpretation, see:\n\n- operations/OPERATIONAL_STATE.md\n- operations/CF_WIRE_STATUS.md\n\n---\n\n## 13. Source-of-Truth Map for Internal Readers\n\n| If you need to understand...     | Start here                                     | Then go deeper into...                                               |\n| -------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------- |\n| the full system                  | this document                                  | ARCHITECTURE_CANONICAL.md, definitive system flow, operational state |\n| **canonical architecture**       | **docs/ARCHITECTURE_CANONICAL.md**             | supersedes all prior architecture descriptions                       |\n| product identity and positioning | product/positioning-and-product-context.md     | product catalog, solutions, layers by role                           |\n| whole-system data flows          | tech/SYSTEM_FLOW_DEFINITIVE.md                 | data access patterns, spine-to-twin boundary                         |\n| Twin surface ontology            | tech/L2_TWIN_SURFACE_CONTRACT.md               | workbench master plan, surface contract                              |\n| operations and runtime posture   | operations/OPERATIONAL_STATE.md                | deployment, verification, CF wire status                             |\n| onboarding and sync behavior     | operations/ONBOARDING_TO_SYNC_SPECIFICATION.md | developer onboarding, API reference                                  |\n| storage/data access law          | tech/DATA_ACCESS_PATTERNS.md                   | architecture decisions, flow documents                               |\n| public-site and design transfer  | design docs                                    | website specs, context transfer docs                                 |\n\n---\n\n## 14. Internal Documentation Rules\n\n### What should live in internal docs\n\nInternal docs may be:\n\n- descriptive\n- narrative\n- system-defining\n- table-heavy where useful\n- cross-cutting\n- implementation-aware\n- operationally specific\n\nThey may include:\n\n- table views\n- DB object maps\n- internal reporting views\n- Coda-oriented representations\n- runtime notes\n- doctrine boundaries\n- cross-surface descriptions\n\n### What internal docs should not become\n\nThey should not become:\n\n- random fragments with no canonical ownership\n- only thin mirrors of engineering notes\n- public-marketing copy disguised as internal truth\n- stale architecture folklore with no path to deeper source docs\n\n### Canonical documentation posture\n\nInternal docs should speak about the whole system when needed.\nThey should help a serious internal reader understand:\n\n- what the system is\n- how the parts connect\n- where truth lives\n- where context lives\n- how AI memory works\n- how governance works\n- which table/view abstractions matter\n- where to go next for depth\n\n---\n\n## 15. Final Summary\n\nIntegrateWise should be understood as one governed operating environment with:\n\n- one Adaptive Spine\n- three surfaces (Operational Workbench, Twin Workbench, Memory View)\n- three major data flows (Flow A: structured truth, Flow B: context, Flow C: governed AI memory)\n- one convergence layer in Entity 360\n- one governed path from reasoning to handoff — execution stays in the user's own stack\n- one documentation responsibility to explain the system coherently\n\nGovernance is not a surface. It is embedded at every layer.\nThe Twin proposes. The human approves. The user's agentic claw executes.\n\nThat means internal docs must do more than list features or folders.\nThey must describe the full operating logic of the system.\nThis page is the first reference layer for that responsibility.\n\n---\n\nRelated docs:\n\n- docs/ARCHITECTURE_CANONICAL.md — THE canonical architecture (supersedes all prior)\n- SYSTEM_FLOW_DEFINITIVE.md\n- DATA_ACCESS_PATTERNS.md\n- OPERATIONAL_STATE.md\n- L2_TWIN_SURFACE_CONTRACT.md\n- CF_WIRE_STATUS.md\n"}