{"slug":"internal/architecture/SYSTEM_WRITEUP_2026-08-20","title":"IntegrateWise Full System Writeup","section":"internal","sectionLabel":"Internal","status":"unclassified","type":"document","path":"internal/architecture/SYSTEM_WRITEUP_2026-08-20.mdx","bytes":11889,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Date:** 2026-08-20\n**Status:** Assessment snapshot — not canonical architecture\n\n---\n\n## Overview\n\nIntegrateWise is structured as a platform monorepo centered on governed operational continuity rather than a single standalone application. The repository combines user-facing apps, reusable domain and platform packages, deployable backend services, integration layers, infrastructure assets, migrations, and testing suites under a single workspace-oriented codebase.\n\nThe strongest architectural pattern is separation of concerns across presentation, reusable platform logic, and runtime execution. Apps appear to own product surfaces and user journeys, packages hold contracts and reusable logic, and services implement operational execution for context, governance, ingestion, orchestration, and AI-related runtime paths.\n\n## Monorepo structure\n\nAt the root level, the repository includes major domains such as `apps`, `packages`, `services`, `mcp`, `marketplace`, `infrastructure`, `migrations`, `sql-migrations`, `supabase`, `scripts`, and `tests`. It also contains architecture and deployment documents, configuration files for TypeScript and Turborepo, multiple Wrangler deployment files, and repo-level validation commands exposed through the root package manifest.\n\nThis structure indicates a platform intended to support multiple product surfaces and multiple runtime paths rather than a single web deployment. It also suggests the repo is used as the control point for architecture policy, release checks, continuity verification, and environment-aware deployment workflows.\n\n## Apps layer\n\nThe app layer contains sixteen product surfaces that cover public web, workspace experiences, platform consoles, One Access identity and connectivity flows, documentation, marketing, and device-oriented clients. Visible app names include `web`, `workspace`, `platform`, `platform-console`, `desktop`, `mobile`, `auth`, `activation`, `connector`, `one-access`, `one-access-console`, `marketing`, `marketing-sites`, `portfolio`, `docs`, and `mcp-servers`.\n\nThis breadth suggests the frontend is intentionally decomposed by user journey and operating context rather than bundled into a single monolith. The main architectural risk in this layer is overlap between adjacent surfaces such as `web`, `workspace`, `platform`, and console variants, which can create duplicated route ownership or diverging user experience logic unless strict product-surface boundaries are documented and enforced.\n\n## Packages layer\n\nThe packages layer contains more than sixty reusable modules and functions as the internal operating system of the platform. The visible package groups span platform foundations, canonical context and Spine modeling, connectors and provider abstractions, orchestration and governance, intelligence and normalization, projection and UI systems, and contracts or integration-test tooling.\n\nRepresentative foundational modules include `core`, `kernel`, `bootstrap`, `config`, `types`, `sdk`, and `api`. Context and Spine-related modules include `context`, `context-contracts`, `spine-entities`, `spine-network`, `spine-schema`, `spine-schema-generator`, and `hermes-spine-memory`. Integration-oriented packages include `connectors`, `connector-contracts`, `connector-utils`, `adapters`, `provider-base`, `webhooks`, and `host-platform-connector`.\n\nExecution and governance packages include `capability`, `orchestrator`, `adk`, `omni-router`, `rbac`, `tenancy`, and `gateway-sdk`. Intelligence and dataflow packages include `intelligence`, `model-gateway`, `normalizer`, `loader`, `skills`, and `analytics`. Projection and UI packages include `projection-engine`, `projection-contracts`, `workbenches`, `workbench-config`, `ui`, `design-system`, and `one-access-ui`.\n\nThe package architecture is not a random utility split. It reflects a deliberate platform model built around context, governed capability execution, projection, and shared contracts.\n\n## Services layer\n\nThe services layer contains more than forty deployable backend components, which points to a domain-service or edge-service runtime model rather than a single centralized API process. Service names indicate clear functional segmentation across gateway, tenancy, administration, telemetry, context, Spine, projection, signals, ingestion, loader, normalizer, pipeline, capability execution, governance, workflow, AI runtime, and MCP connectivity.\n\nExamples of control-plane and operational services include `gateway`, `core-engine`, `tenants`, `admin`, `store`, `telemetry`, `billing`, and `continuity`. Context-centric services include `context`, `context-fetch`, `spine`, `projection`, `signals`, `knowledge`, and `schema-ai`. Execution and orchestration services include `capability`, `govern`, `hermes`, `workflow`, `task-management`, and `twin-orchestrator`.\n\nThe AI and agent runtime cluster includes `intelligence`, `iw-agent-runtime`, `agent-registry`, `ai-provider-mcp`, `huggingface-inference`, and `mcp-pool`. The MCP ecosystem also appears as a first-class service domain through modules such as `mcp-connector`, `integration-management-mcp`, `provider-management-mcp`, `vercel-mcp`, and `marketplace-installation`.\n\n## Tooling and delivery\n\nThe repo uses pnpm workspaces together with Turborepo for monorepo orchestration. Root scripts expose workspace-wide commands for development, testing, linting, typechecking, builds, architecture checks, continuity verification, governed-chain testing, and release flows.\n\nThe Playwright configuration runs tests from `tests/playwright/suites`, targets a local development server at `http://localhost:3000`, and executes across Chromium, Firefox, and WebKit with retries in CI plus retained trace, screenshot, and video diagnostics on failure paths. This indicates an intention to support browser-level validation in addition to API and contract testing.\n\nDeployment is strongly Cloudflare-oriented, based on the presence of multiple Wrangler configuration files and deployment scripts for gateway, intelligence, and pipeline services. The release flow includes explicit scripts for release checking, packaging, deployment, and post-deployment verification, which is a positive signal for operational discipline.\n\n## Architectural strengths\n\nA major strength is the clear conceptual split between apps, reusable packages, and runtime services. That separation makes it possible to scale user experiences, backend execution, and platform contracts independently when the boundaries are actively enforced.\n\nA second strength is the degree of explicit architecture and governance embedded in the repo itself. The presence of scripts such as `check:architecture`, `verify:continuity`, `verify:total-end-state`, `check:deployment-policy`, and governed-chain tests suggests the team is trying to encode doctrine and runtime guarantees as executable verification rather than leaving them as design intent only.\n\nA third strength is the platform's apparent commitment to canonical context and governed execution instead of direct UI-owned truth or uncontrolled provider access. The package and service naming consistently reinforces a model in which context, projection, orchestration, capability control, and memory promotion are treated as first-class system primitives.\n\n## System gaps\n\nThe most important gap is runtime completeness. Existing evidence indicates some product actions and persistence paths are still incomplete, including TODO handlers in Sales Workbench interactions, a generic unimplemented section route, a missing mock-data fallback when MCP Pool is unavailable, and a timeline route that still contains a placeholder for the actual Supabase write path.\n\nAnother gap is the contradiction between architectural claims and runtime proof. The forensic reconciliation document states that a previous conclusion of completion was invalid, describes unresolved runtime endpoint issues, and notes that some earlier validation focused on constants and comments rather than executed UI, persistence, or real route behavior. This raises a release-readiness problem because the architecture is ambitious, but the available evidence suggests not all critical paths are proven in deployed conditions.\n\nA further structural gap is monorepo coverage consistency. The workspace configuration includes key directories such as `services/*`, `packages/*`, and `apps/*`, but not all top-level runtime domains are clearly represented as standard workspaces, which creates a risk that some folders may sit outside regular test, typecheck, or release enforcement unless handled separately.\n\n## Frontend gaps\n\nThe frontend gap is not only missing screens; it is incomplete representation of platform truth. The system doctrine expects the frontend to show authoritative workflow states such as approval-required, queued, executing, observing, verified, failed, or compensated while avoiding direct ownership of policy truth or canonical records.\n\nCurrent evidence suggests the frontend is ahead of live platform completion in a few places. Sales Workbench actions remain partially stubbed, route coverage is incomplete in at least one work-view path, MCP fallback behavior is missing, and durable mutation readback is not yet consistently guaranteed for timeline or memory-driven operations.\n\nThat creates a UX risk where the interface can appear operational before the underlying system has produced durable, reconciled, audited results. For an operations platform, this is more severe than a normal feature gap because user trust depends on evidence-backed state transitions, not optimistic client behavior.\n\n## End-to-end coverage\n\nThe existing Playwright continuity-loop suite already models the intended business path at the API level: signal ingestion, proposal creation, approval, dispatch, outcome submission, and memory search. However, the current suite is not yet a complete full-system golden-path test because it relies on direct API calls, uses fixed sleeps, and only partially verifies downstream user-visible readback.\n\nA true end-to-end loop for this platform should prove the full chain from authenticated tenant context through ingestion, normalization, Spine update, projection refresh, governed action, provider-facing execution, reconciliation, evidence generation, and verified frontend readback. That standard is higher than ordinary browser smoke testing because the product promise depends on continuity and governance being real, not implied.\n\n## Priority improvements\n\n- **Prove a golden path in a deployable environment:** authenticated tenant resolution, provider or signal ingestion, canonical context update, Workbench rendering, governed action, reconciliation, and verified UI readback.\n- **Close persistence and degraded-mode gaps:** timeline writes, memory promotion visibility, connector outages, MCP Pool degradation, and provider failure states should all be explicit and tested.\n- **Publish module-level ownership:** each app, package, and service should declare owner, maturity, deployability, allowed dependencies, and exact role in the continuity loop.\n\n## Assessment\n\nIntegrateWise has the architecture of a serious platform, with unusually explicit attention to governed execution, canonical context, and continuity verification. Its design intent is strong and differentiated, especially where it treats AI and agents as bounded participants inside a governed operational system rather than as autonomous system-of-record substitutes.\n\nThe main challenge is not conceptual ambition but proof and completion. The repo already contains the right categories of code and verification hooks, but the remaining work is to eliminate TODO paths, close readback and persistence gaps, harden degraded states, and convert architectural doctrine into indisputable end-to-end runtime evidence.\n"}