Unclassified

IntegrateWise — Wiring & Integration Map

Purpose. The codebase is ~99% built but the parts are wired together
inconsistently, so many components exist as islands: real code that is
never reached at runtime. This document is derived only from the code
(package.json, wrangler.toml, tsconfig.json, and source imports — no
prose/docs were used) and lists, per wiring plane, exactly what is connected,
what is an island, and the precise change needed to connect it for live
release.

Generated by static analysis of the repository on branch
claude/codebase-wiring-integration-tmih1t.

0. Topology at a glance

Layer	Count	Stack	How they wire together
Apps	5 (`web`, `marketing`, `mobile`, `desktop`, `portfolio`)	Vite + React Router SPA (`web`)	HTTP → gateway
Shared packages	~35 (`packages/*`)	TS libraries	`package.json` deps + `@integratewise/*` imports
Backend services	36 (`services/*`)	Cloudflare Workers	Cloudflare service bindings (`[[services]]` in `wrangler.toml`)
Deploy target	Cloudflare only	`wrangler`	Netlify + Vercel are disabled (`netlify.toml` → `ignore = "exit 0"`, `vercel.json` → `deploymentEnabled: false`)

71 workspaces are resolved by pnpm-workspace.yaml. The frontend build
injects VITE_API_BASE_URL (the gateway URL) at build time; every backend
worker reaches its peers through named service bindings.

There are five wiring planes, and there is at least one break in four of them:

Service mesh (Worker → Worker via Cloudflare bindings) — 10 broken targets + 1 name collision ← primary release blocker
Gateway routing (frontend API contract → downstream bindings) — code is correct but rides on 3 broken bindings
Frontend → backend (SPA → gateway) — no central client; 21 files each invent their own base URL
Shared package graph (apps/services → packages/*) — 8 library packages are built but imported nowhere
Frontend-internal (routes, module map, marketing) — duplicated marketing surface + 103 _deprecated files still in the tree

1. Wiring Plane 1 — Service mesh (Cloudflare service bindings) 🚨 P0

Cloudflare service bindings connect Workers by name: a [[services]]
block's service = "<worker-name>" must equal the actual top-level name
of the target Worker, or wrangler deploy fails / the binding resolves to
nothing at runtime. There are 75 bindings across the mesh; 10 distinct
targets reference a Worker name that no Worker actually declares.

1.1 The naming split (root cause)

Worker names are inconsistent. Some services use a bare name, others an
integratewise- prefix:

Bare-named workers	`integratewise-`-prefixed workers
`connector`, `continuity`, `gateway`, `intelligence`, `knowledge`, `l2`, `workflow`, `iw-agent-runtime`, `twin-orchestrator`, `hub-controller-api`	everything else (`integratewise-pipeline`, `integratewise-mcp-connector`, `integratewise-hermes`, …)

Callers guessed the wrong side of the split. The bindings assume a uniform
integratewise-* scheme (or a uniform bare scheme) that the deploy targets do
not follow.

1.2 Broken binding targets (verified — none of these names is declared by any Worker, in any environment)

Referenced target (`service = …`)	Actual deployed Worker	Callers (`worker(BINDING_VAR)`)
`integratewise-intelligence`	`intelligence`	`gateway(INTELLIGENCE)`, `integratewise-act(GOVERN)`, `integratewise-hermes(THINK)`, `integratewise-hermes(ACT)`, `knowledge(THINK)`, `integratewise-mcp-connector(INTELLIGENCE)`, `integratewise-pipeline(INTELLIGENCE)`, `integratewise-think(ACT)`, `integratewise-think(GOVERN)`, `integratewise-think(AGENTS)`
`integratewise-knowledge`	`knowledge`	`gateway(KNOWLEDGE)`, `continuity(KNOWLEDGE)`, `integratewise-hermes(KNOWLEDGE)`, `intelligence(KNOWLEDGE)`, `iw-agent-runtime(KNOWLEDGE)`, `knowledge(IQ_HUB)`, `integratewise-mcp-connector(KNOWLEDGE)`, `integratewise-pipeline(KNOWLEDGE)`, `twin-orchestrator(KNOWLEDGE)`
`integratewise-connector`	`connector`	`integratewise-act(CONNECTOR)`, `integratewise-connector-sync(CONNECTOR)`, `intelligence(CONNECTOR)`, `iw-agent-runtime(CONNECTOR)`, `integratewise-webhook-ingress(CONNECTOR)`
`integratewise-continuity`	`continuity`	`integratewise-hermes(CONTINUITY)`
`integratewise-l2`	`l2`	`gateway(L2)`
`integratewise-workflow`	`workflow`	`intelligence(WORKFLOW)`
`integratewise-bff`	`workflow` (workflow is the BFF)	`integratewise-hermes(WORKFLOW)`, `integratewise-normalizer(BFF)`, `integratewise-webhook-ingress(BFF)`
`pipeline`	`integratewise-pipeline`	`workflow(SPINE)`
`mcp-connector`	`integratewise-mcp-connector`	`connector(MCP)`
`integratewise-integration-management-mcp-prod`	`integratewise-integration-management-mcp` (stale `-prod` suffix; no such env-named worker exists)	`integratewise-mcp-pool(INTEGRATION_MANAGEMENT)` × 3 blocks

Impact: the core cognitive + knowledge + connector chains are severed.
intelligence, knowledge, continuity, connector, l2, and workflow
are the busiest hubs in the mesh, and they are exactly the ones addressed by
the wrong name. Anything that calls Think/Act/Govern, Knowledge search, or the
connector plane through a binding is calling a dead reference.

1.3 Worker-name collision (verified)

Two different directories declare the same Worker name — they will
overwrite each other on deploy:

Directory	`name`	`main`
`services/mcp-connector`	`integratewise-mcp-connector`	`src/index.ts`
`packages/integratewise-mcp-tool-connector`	`integratewise-mcp-connector`	`dist/worker.js`

Whichever deploys last wins the name integratewise-mcp-connector; the other's
code silently disappears from the URL every binding points at.

1.4 Fix (lowest-risk path)

Renaming a live Worker changes its URL and route bindings, so the safe move for
a release is to fix the service = targets to match the already-deployed
names, and pick one canonical name for the mcp-connector collision:

integratewise-intelligence → intelligence
integratewise-knowledge → knowledge
integratewise-connector → connector
integratewise-continuity → continuity
integratewise-l2 → l2
integratewise-workflow and integratewise-bff → workflow
pipeline → integratewise-pipeline
mcp-connector → integratewise-mcp-connector
integratewise-integration-management-mcp-prod → integratewise-integration-management-mcp
Give packages/integratewise-mcp-tool-connector a distinct name (e.g. integratewise-mcp-tool-connector) or remove it if superseded by services/mcp-connector.

Then adopt a single naming convention repo-wide (recommend integratewise-*
everywhere, executed as a coordinated rename + binding update) so this class of
bug cannot recur. A lint/CI check that asserts "every service = target
exists as a declared name" would have caught all 10.

2. Wiring Plane 2 — Gateway routing (frontend API contract)

services/gateway/src/index.ts (2,618 lines) is the single front door. It owns
a ROUTES table (const ROUTES: [string, RouteTarget][]) mapping URL prefixes
to binding names, e.g.:

Prefix	Binding	Downstream worker
`/api/v1/connector`, `/connectors`, `/loader`, `/continuity-bridge`	`CONNECTOR`	`integratewise-mcp-connector`
`/api/v1/pipeline`, `/entity360`, `/identity`, `/cognitive/spine`	`PIPELINE`	`integratewise-pipeline` ✅
`/api/v1/intelligence`, `/agents`, `/cognitive/{think,act,govern,signals}`, `/brainstorm`	`INTELLIGENCE`	`integratewise-intelligence` ❌ (broken — see §1.2)
`/api/v1/knowledge`, `/cognitive/memories`	`KNOWLEDGE`	`integratewise-knowledge` ❌ (broken)
`/api/v1/workspace`, `/analytics`, `/cognitive/{evidence,hitl}`	`BFF`	`workflow` ✅
(L2 surface)	`L2`	`integratewise-l2` ❌ (broken)

The routing logic is correct; the bindings under it are not. The gateway
does the right thing for every request, then hands three of its most important
targets (Intelligence, Knowledge, L2) to bindings that resolve to nothing.
Fixing Plane 1 lights up Plane 2 with no code change to the router itself.

3. Wiring Plane 3 — Frontend → backend (SPA → gateway)

The web app is a Vite + React Router SPA (apps/web, entry
src/main.tsx → src/App.tsx, router in src/routes.tsx). It reaches the
backend over HTTP using VITE_API_BASE_URL.

3.1 No centralized API client

VITE_API_BASE_URL is read in 21 separate files, each re-declaring its own
API_BASE with an inconsistent fallback:

Fallback used	Occurrences	Effect when `VITE_API_BASE_URL` is unset
`\|\| ""` (same-origin)	6	calls `/(path)` on the static-asset origin — no backend there
`\|\| "http://localhost:8786"`	5	hardcoded to a local dev worker — dead in prod
`\|\| "/api/v1"`	1	same-origin relative
`\|\| "https://gateway.integratewise.ai"`	2	the only prod-correct fallback
bare `import.meta.env.VITE_API_BASE_URL` (no fallback)	several	`undefined` → `undefined/path`

A canonical helper exists (apps/web/src/lib/api.ts,
const API_BASE = import.meta.env.VITE_API_BASE_URL; // Gateway worker URL) but
is not the single source most components use. Examples of the drift:

src/api/workspace-api.ts:112 → || "/api/v1"
src/components/core/auth/auth-provider.tsx:69,198 → || "" then API_BASE || "https://gateway.integratewise.ai"
src/hooks/use-twin-chat.ts:23 and src/components/l1/twin/twin-workbench.tsx:79 → || "http://localhost:8786"
src/hooks/useSchemaDashboard.ts:83 → bare ${VITE_API_BASE_URL}/bff/v1/dashboard (breaks if unset)

There are 115 fetch() call sites in the web app; because each resolves its
base independently, a single missing/incorrect build var yields partial
breakage (some views hit prod, some hit localhost, some hit the asset origin) —
the hardest failure mode to diagnose.

3.2 Fix

Route all frontend calls through one module (src/lib/api.ts) that resolves
the base once, fails loudly if VITE_API_BASE_URL is missing in a production
build, and drops every hardcoded http://localhost:8786 / "" fallback.
.env.example already documents VITE_API_BASE_URL=http://localhost:8786
(line 48) — the wiring gap is enforcement, not documentation.

4. Wiring Plane 4 — Shared package graph (island libraries)

Internal dependency edges were extracted from every workspace package.json
(@integratewise/* / @iw/*) and confirmed against actual source imports.
@integratewise/types is healthy (imported by 30 workspaces); the connector/
lib core (connector-utils, connectors, connector-contracts, lib) is
wired. But several whole library packages are imported by zero source files
anywhere outside their own directory — they are complete islands:

Package	Source importers (excl. self)	Note
`@integratewise/ui`	0	A full UI library. The web app instead ships 548 components under `src/components/*` and consumes `@radix-ui/` directly.
`@integratewise/design-system`	0	Design tokens/system unused; web app uses `src/figma-theme-merged.css` + local tokens.
`@integratewise/db`	0	DB package referenced by nothing.
`@integratewise/analytics`	0	(web app uses `src/clients/analytics/*` instead)
`@integratewise/hermes-spine-memory`	0
`@integratewise/knowledge-bank-ui`	0
`@integratewise/handoff-adapters`	0
`@integratewise/coda-pack`	0
`@integratewise/auth`	1	barely wired; web app uses `@descope/web-js-sdk` + local `src/components/core/auth/*`

For each island, decide connect or delete: either route real usage through
the package (e.g. make apps/web consume @integratewise/ui /
design-system instead of its private component tree) or remove the package so
the graph reflects reality. Note the web app declares only 5 internal deps
(config, core, rbac, types, workbench-config) — it is deliberately
decoupled from the shared UI/auth/db packages today.

5. Wiring Plane 5 — Frontend-internal wiring

Route table (src/routes.tsx, createAppRouter()): top-level routes are
slug-driven off src/lib/router-config.ts (MODULE_ROUTES, 13 modules:
dashboard, accounts, contacts, meetings, tasks, calendar, docs, knowledge,
pipeline, deals, analytics, settings, home). /app/:module → AppShell,
marketing slugs → MarketingShell, /marketplace, /onboarding,
/auth/callback, /oauth/callback/:provider. This layer is coherent.
Duplicated marketing surface: marketing lives in two places —
apps/web/src/pages/marketing/* (14 pages, wired into the SPA router) and
a separate apps/marketing app. Pick one as canonical to avoid drift.
Dead code in the tree: 103 files under apps/web/src/**/_deprecated/
(components/_deprecated, hooks/_deprecated), plus files explicitly
excluded in apps/web/tsconfig.json (e.g.
components/workbench/views/department-data-grid.tsx,
pages/work/accounts/account-detail.tsx). These inflate the surface and hide
which components are actually reachable — delete or quarantine before release.
Root config oddities to confirm: root wrangler.jsonc names the project
integratewise-live with assets.directory pointing at
services/connector-sync (a service source dir, not a built asset dir) — verify
this is intentional. next.config.mjs exists at root although the web app is
Vite, not Next — a leftover that can mislead tooling.

6. Prioritized path to live release

Priority	Action	Plane	Why
P0	Fix the 10 broken service-binding targets (§1.2) and resolve the `integratewise-mcp-connector` name collision (§1.3).	1	Core cognitive/knowledge/connector chains are dead until this lands. Unblocks Plane 2 automatically.
P0	Add a CI check: every `wrangler.toml` `service =` target must exist as a declared Worker `name`.	1	Prevents regression of the whole class of bug.
P1	Consolidate frontend API access into `src/lib/api.ts`; require `VITE_API_BASE_URL`; remove `localhost`/`""` fallbacks (§3).	3	Eliminates partial-breakage-by-view in production.
P1	Standardize Worker naming on one convention (recommend `integratewise-*`) via a coordinated rename + binding update.	1	Makes the mesh self-consistent and legible.
P2	For each island package (§4), decide connect-or-delete.	4	Removes dead weight / recovers intended reuse (esp. `ui`, `design-system`).
P2	De-duplicate the marketing surface; delete the 103 `_deprecated` files; verify root `wrangler.jsonc` assets dir and remove the stray root `next.config.mjs`.	5	Shrinks the reachable surface for a clean launch.

Appendix A — Full service-binding matrix (as coded today)

connector             MCP→mcp-connector✗  KNOWLEDGE→knowledge✅  LOADER→integratewise-loader✅
                      MCP→integratewise-mcp-connector✅ (dup var)  STORE→integratewise-store✅
continuity            KNOWLEDGE→integratewise-knowledge✗  PIPELINE→integratewise-pipeline✅
gateway               PIPELINE→integratewise-pipeline✅  AGENT_RUNTIME→iw-agent-runtime✅
                      INTELLIGENCE→integratewise-intelligence✗  CONNECTOR→integratewise-mcp-connector✅
                      CONNECTOR_SYNC→integratewise-connector-sync✅  KNOWLEDGE→integratewise-knowledge✗
                      BFF→workflow✅  L2→integratewise-l2✗  WEBHOOK_INGRESS→integratewise-webhook-ingress✅
                      HUB_CONTROLLER→hub-controller-api✅  ADMIN→integratewise-admin✅
                      BILLING→integratewise-billing✅  TENANTS→integratewise-tenants✅
integratewise-act     CONNECTOR→integratewise-connector✗  GOVERN→integratewise-intelligence✗  PIPELINE→integratewise-pipeline✅
integratewise-agent-registry   PIPELINE→integratewise-pipeline✅
integratewise-connector-sync   CONNECTOR→integratewise-connector✗
integratewise-hermes  SPINE→integratewise-pipeline✅  KNOWLEDGE→integratewise-knowledge✗  THINK→integratewise-intelligence✗
                      ACT→integratewise-intelligence✗  CONTINUITY→integratewise-continuity✗  WORKFLOW→integratewise-bff✗
integratewise-loader  MCP→integratewise-mcp-connector✅
integratewise-mcp-connector  KNOWLEDGE→integratewise-knowledge✗  CONTINUITY→continuity✅  PIPELINE→integratewise-pipeline✅
                      INTELLIGENCE→integratewise-intelligence✗  AGENT_RUNTIME→iw-agent-runtime✅
integratewise-mcp-pool  INTEGRATION_MANAGEMENT→integratewise-integration-management-mcp-prod✗  SPINE→integratewise-spine✅
integratewise-normalizer  SPINE→integratewise-pipeline✅  BFF→integratewise-bff✗
integratewise-pipeline  KNOWLEDGE→integratewise-knowledge✗  MCP→integratewise-mcp-connector✅  INTELLIGENCE→integratewise-intelligence✗
integratewise-task-management  TASK_MANAGEMENT→integratewise-task-management✅  MCP_POOL→integratewise-mcp-pool✅
integratewise-tenants  CONNECTOR_SYNC→integratewise-connector-sync✅
integratewise-think   ACT→integratewise-intelligence✗  GOVERN→integratewise-intelligence✗  AGENTS→integratewise-intelligence✗
integratewise-webhook-ingress  MCP→integratewise-mcp-connector✅  BFF→integratewise-bff✗  CONNECTOR→integratewise-connector✗
intelligence          CONNECTOR→integratewise-connector✗  WORKFLOW→integratewise-workflow✗  KNOWLEDGE→integratewise-knowledge✗  PIPELINE→integratewise-pipeline✅
iw-agent-runtime      INTELLIGENCE→intelligence✅  PIPELINE→integratewise-pipeline✅  CONTINUITY→continuity✅  CONNECTOR→integratewise-connector✗  KNOWLEDGE→integratewise-knowledge✗
knowledge             PIPELINE→integratewise-pipeline✅  THINK→integratewise-intelligence✗  IQ_HUB→integratewise-knowledge✗
twin-orchestrator     MCP_CONNECTOR→integratewise-mcp-connector✅  INTELLIGENCE→intelligence✅  PIPELINE→integratewise-pipeline✅  KNOWLEDGE→integratewise-knowledge✗  CONTINUITY→continuity✅
workflow              SPINE→pipeline✗  CONNECTOR→connector✅  KNOWLEDGE→knowledge✅  THINK→intelligence✅  ACT→intelligence✅

✅ = target name exists · ✗ = target name matches no declared Worker (broken)

Appendix B — Directory → canonical Worker name

Directory	Worker `name`	Directory	Worker `name`
services/connector	`connector`	services/intelligence	`intelligence`
services/continuity	`continuity`	services/knowledge	`knowledge`
services/gateway	`gateway`	services/l2	`l2`
services/workflow	`workflow`	services/pipeline	`integratewise-pipeline`
services/iw-agent-runtime	`iw-agent-runtime`	services/twin-orchestrator	`twin-orchestrator`
services/mcp-connector	`integratewise-mcp-connector`	packages/integratewise-mcp-tool-connector	`integratewise-mcp-connector` ⚠️ collision
services/hermes	`integratewise-hermes`	services/normalizer	`integratewise-normalizer`
services/spine	`integratewise-spine`	services/store	`integratewise-store`
services/loader	`integratewise-loader`	services/act	`integratewise-act`
services/think	`integratewise-think`	services/govern	`integratewise-govern`
services/admin	`integratewise-admin`	services/billing	`integratewise-billing`
services/tenants	`integratewise-tenants`	services/connector-sync	`integratewise-connector-sync`
services/webhook-ingress	`integratewise-webhook-ingress`	services/mcp-pool	`integratewise-mcp-pool`
services/task-management	`integratewise-task-management`	services/agent-registry	`integratewise-agent-registry`
services/telemetry	`integratewise-telemetry`	services/signals	`integratewise-signals`
services/schema-ai	`integratewise-schema-ai`	services/folder-watcher	`integratewise-folder-watcher`
services/vercel-mcp	`integratewise-vercel-mcp`	services/integration-management-mcp	`integratewise-integration-management-mcp`
services/provider-management-mcp	`integratewise-provider-management-mcp`	packages/api	`hub-controller-api`
packages/webhooks	`integratewise-webhooks`