Unclassified

IntegrateWise Platform → Backend Services Map

Complete Frontend-to-Backend Architecture Audit

Generated: August 6, 2026
Scope: apps/platform only (management console UI)
Status: Production Ready

PLATFORM OVERVIEW

Location: apps/platform
Type: Next.js 16 App Router (React 19)
Role: Operational Control Plane UI for tenant/connector/capability management
Auth: Clerk (email + password, OAuth ready)
API Surface: /api/v1/* (fronted by Gateway service)

CORE RULE

Platform UI never owns truth — all state lives in backend D1/Neon
Platform UI never talks directly to storage — routes through /api/v1 only
Platform UI consumes governed APIs — no auth bypass
Backend services own capability — business logic is service-owned
Spine owns operational state — immutable event log
Neon owns control plane — tenants, orgs, subscriptions, entitlements
D1 operates tenant runtime — entity registry, policies, capabilities

GOLDEN LOOP

User Action
    ↓
Platform UI Component
    ↓
fetch(/api/v1/*)
    ↓
Gateway (validation, auth, routing)
    ↓
Backend Service (business logic)
    ↓
D1 / Neon / Spine (truth)
    ↓
Event Emitted
    ↓
Projection Updated
    ↓
Platform UI Re-renders (SWR cache refresh)

ENTRY & AUTH LAYER

Auth Flow

Platform URL
    ↓
Clerk Session Check (middleware)
    ↓
Session Valid?
    ├─ YES → Resolve tenant context → Dashboard
    └─ NO → /login (Clerk)

Session Endpoints

GET /api/v1/auth/session → services/tenants + services/admin
- Returns: { user, tenant, permissions, role }
- SWR Hook: useSession()

Key Management

GET /api/v1/keys → services/admin
- Returns: { apiKeys[], secrets[] }
- SWR Hook: useKeys()

PLATFORM PAGES & SERVICE MAPPING

1. Dashboard (`/`)

Component: app/(shell)/page.tsx
Role: Entry point, operational summary

Displays:

Tenant overview
Recent activity
Key metrics

Services: tenants, admin
APIs: None (static initial render, SWR populates later)

2. Workspace (`/workspace`)

Component: app/(shell)/workspace/page.tsx
Role: Central discovery and workspace state

Displays:

Workspace topology
Connected systems
Capability registry

Services: spine, intelligence, gateway
APIs:

GET /api/v1/workspace/discovery → workspace state projection
GET /api/v1/workspace/bootstrap → initial workspace load

Data Flow:

useWorkspaceDiscovery()
    ↓
fetch(/api/v1/workspace/discovery)
    ↓
Gateway → Intelligence Service
    ↓
D1: workspace_metadata, entity_registry, capability_registry
    ↓
SWR Cache → Component re-renders

3. Connectors (`/connectors`)

Component: app/(shell)/connectors/page.tsx
Role: Connector lifecycle & management

Displays:

Installed connectors
Connection status
Sync configuration
Health metrics

Services: connector, connector-sync, integration-management-mcp, provider-management-mcp
APIs:

GET /api/v1/connectors → catalog of connectors
POST /api/v1/connectors/{id}/activate → install connector
DELETE /api/v1/connectors/{id} → remove connector
GET /api/v1/connections → active connections
POST /api/v1/connections → create connection
PATCH /api/v1/connections/{id} → update connection

Connectors Tracked:

Hubspot (CRM)
Salesforce (CRM)
Pipedrive (CRM)
Nango (integration broker)
Zapier (automation)
Custom (user-built)

Data Storage:

D1 Tables:
  - connector_catalog (metadata)
  - tenant_connections (state)
  - entity_sync_state (sync progress)
  - capability_registry (exposed tools)

4. Marketplace (`/marketplace`)

Component: app/(shell)/marketplace/page.tsx
Role: Plugin/MCP/connector discovery

Displays:

Available connectors
MCP servers
Plugins
Installation status

Services: marketplace-installation, provider-management-mcp, integration-management-mcp
APIs:

GET /api/v1/workspace/marketplace-items → available items
POST /api/v1/marketplace/install/{id} → install item
GET /api/v1/marketplace/installed → installed items
DELETE /api/v1/marketplace/{id} → uninstall

5. Network - MCP (`/network/mcp`)

Component: app/(shell)/network/mcp/page.tsx
Role: MCP server registry & tool exposure

Displays:

Registered MCP servers
Exposed tools
Semantic capabilities
Tool permissions

Services: mcp-pool, mcp-connector, provider-management-mcp, intelligence
APIs:

GET /api/v1/connectors/mcp-pool → MCP registry
POST /api/v1/connectors/mcp-pool/register → register server
GET /api/v1/capabilities → semantic tool registry
PATCH /api/v1/capabilities/{id}/permissions → manage access

Data Storage:

D1 Tables:
  - mcp_bindings (MCP ↔ workspace mapping)
  - capability_registry (tool metadata)
  - capability_grants (permissions)

6. Network - General (`/network`)

Component: app/(shell)/network/page.tsx
Role: Topology & system integration

Displays:

Service health
Integration topology
Capability graph
Data flow diagram

Services: spine, intelligence, telemetry, signals
APIs:

GET /api/v1/workspace/topology → system graph
GET /api/v1/signals → real-time metrics

7. Agents (`/agents`)

Component: app/(shell)/agents/page.tsx
Role: Agent lifecycle & orchestration

Displays:

Deployed agents
Agent status
Memory state
Execution logs

Services: agent-registry, iw-agent-runtime, continuity, twin-orchestrator
APIs:

GET /api/v1/agents → agent catalog
POST /api/v1/agents → create agent
PATCH /api/v1/agents/{id} → update config
GET /api/v1/agents/{id}/memory → agent state
GET /api/v1/agents/{id}/sessions → execution history

Data Storage:

D1 Tables:
  - agent_registry (agent metadata)
  - agent_sessions (execution state)
  - memory_entries (agent continuity)
  - continuity_ledger (event log)

8. Approvals (`/approvals`)

Component: app/(shell)/approvals/page.tsx
Role: Governance & workflow approvals

Displays:

Pending approvals
Approval history
Policy audit trail
Execution control

Services: twin-orchestrator, hermes, admin
APIs:

GET /api/v1/workspace/governance/approvals → pending items
POST /api/v1/workspace/governance/approvals/{id}/approve → approve
POST /api/v1/workspace/governance/approvals/{id}/reject → reject
GET /api/v1/workspace/governance/policies → policy registry

Data Storage:

D1 Tables:
  - proposals (pending approvals)
  - approvals (approval decisions)
  - audit_events (governance log)
  - policies (policy registry)

9. Governance (`/governance`)

Component: app/(shell)/governance/page.tsx
Role: Policy & access control

Displays:

Policy rules
Role-based access
Data governance
Compliance state

Services: twin-orchestrator, admin, intelligence
APIs:

GET /api/v1/workspace/governance → policy state
POST /api/v1/workspace/governance/policies → create policy
PATCH /api/v1/workspace/governance/policies/{id} → update policy
GET /api/v1/workspace/governance/audit → audit log

10. My Work (`/my-work`)

Component: app/(shell)/my-work/page.tsx
Role: User task dashboard

Displays:

Assigned tasks
My workflows
Recent activity
Metrics dashboard

Services: task-management, workflow, intelligence
APIs:

GET /api/v1/workflows/my-tasks → assigned work
GET /api/v1/workflows/recent → recent workflows
GET /api/v1/telemetry/personal → user metrics

11. Communications (`/communications`)

Component: app/(shell)/communications/page.tsx
Role: Alerts & notifications

Displays:

System alerts
Integration notifications
Error logs
Event stream

Services: signals, telemetry, webhook-ingress
APIs:

GET /api/v1/signals → real-time events
GET /api/v1/telemetry → metrics
GET /api/v1/workspace/audit → audit events

12. Settings (`/settings`)

Component: app/(shell)/settings/page.tsx
Role: Configuration & preferences

Displays:

Workspace settings
User preferences
Integration config
API keys & secrets

Services: admin, tenants, integration-management-mcp
APIs:

GET /api/v1/workspace/config → workspace settings
PATCH /api/v1/workspace/config → update settings
GET /api/v1/keys → API key management
POST /api/v1/keys → create key
DELETE /api/v1/keys/{id} → revoke key

13. Workbench (`/workbench`)

Component: app/(shell)/workbench/page.tsx
Role: Low-code builder & testing

Displays:

Workflow builder
Schema editor
Test runner
Capability explorer

Services: pipeline, loader, schema-ai, intelligence
APIs:

GET /api/v1/pipelines → pipeline catalog
POST /api/v1/pipelines → create pipeline
POST /api/v1/pipelines/{id}/test → test execution
GET /api/v1/schema → schema registry

14. Control Surface (`/control/[surface]`)

Component: app/(shell)/control/[surface]/page.tsx
Role: Dynamic control panels

Displays:

Runtime controls
System administration
Performance tuning
Deployment config

Services: admin, tenants, gateway
APIs:

GET /api/v1/deployment/config → deployment state
PATCH /api/v1/deployment/config → update deployment
GET /api/v1/runtime/metrics → runtime metrics

API CLIENT LAYER

`lib/api-client.ts`

SWR Fetchers (automatic caching & request deduplication):

// Authentication
useSession() → GET /api/v1/auth/session
useKeys() → GET /api/v1/keys

// Connections & Integrations
useConnections() → GET /api/v1/connections
useConnectorProjections() → GET /api/v1/connectors

// Workspace Discovery
useWorkspaceDiscovery(skip?) → GET /api/v1/workspace/discovery
  - Returns canonical workspace projection
  - Skips fetch until session confirmed (conditional SWR)

Direct Fetch Helpers:

request<T>(path, options?) → authenticated fetch to /api/v1{path}
  - Auto-attaches auth headers
  - Returns typed JSON
  - Throws on auth failure

COMPONENT ARCHITECTURE

Platform Shell Layout

app/(shell)/layout.tsx
  ├── Navbar (with tenant selector, user menu)
  ├── Sidebar (navigation)
  ├── TenantProvider (context)
  └── Page Routes
      ├── /
      ├── /workspace
      ├── /connectors
      ├── /marketplace
      ├── /network/mcp
      ├── /network
      ├── /agents
      ├── /approvals
      ├── /governance
      ├── /my-work
      ├── /communications
      ├── /settings
      └── /workbench

Reusable Components

ConnectorCard: Display connector + status
CapabilityGrid: Tool registry visualization
AgentPanel: Agent state display
PolicyEditor: Governance rule builder
WorkflowBuilder: Low-code editor

DATA FLOW PATTERNS

Pattern 1: Fetch-on-Load + Cache

Component Mount
  ↓
SWR Hook (useSWR)
  ↓
fetch(/api/v1/*)
  ↓
Gateway validates auth + routes
  ↓
Service fetches from D1
  ↓
Response cached in SWR
  ↓
Component renders (sync)

Pattern 2: User Action + Mutation

User clicks button
  ↓
Form submission / Event handler
  ↓
fetch(POST /api/v1/*, { body })
  ↓
Gateway routes to service
  ↓
Service validates + stores in D1
  ↓
Event emitted (D1 → Redis Pub/Sub)
  ↓
SWR cache invalidated (mutate)
  ↓
Component refetches & re-renders

Pattern 3: Real-Time Updates

Webhook received (from external system)
  ↓
webhook-ingress service
  ↓
Event stored in D1 + Spine
  ↓
Projection updated
  ↓
WebSocket broadcast (if enabled)
  ↓
Platform UI subscribes + updates

BACKEND SERVICES DIRECT TO PLATFORM

Core Services (✓ Platform Consumes)

Service	Role	APIs	D1 Tables
gateway	Request routing, auth validation, tenant binding	All /api/v1/* routes	-
tenants	Tenant lifecycle, provisioning, context	/api/v1/auth/session, /api/v1/tenants	tenants, organizations, subscriptions
admin	User, role, permission management	/api/v1/keys, /api/v1/users, /api/v1/roles	users, memberships, roles, permissions
connector	Connector activation, state	/api/v1/connectors, /api/v1/connectors/{id}	connector_catalog, tenant_connections
connector-sync	Sync orchestration, state tracking	/api/v1/connections, /api/v1/connectors/sync	entity_sync_state, sync_history
integration-management-mcp	Connector metadata, OAuth flows	/api/v1/connections/oauth, /api/v1/marketplace/connectors	integration_catalog, oauth_state
provider-management-mcp	Provider registry, capability exposure	/api/v1/capabilities, /api/v1/connectors/providers	capability_registry, provider_catalog
mcp-pool	MCP server registry & management	/api/v1/connectors/mcp-pool, /api/v1/capabilities	mcp_bindings, capability_registry
mcp-connector	MCP tool invocation	/api/v1/connectors/mcp-pool/invoke	tool_invocations
agent-registry	Agent metadata & lifecycle	/api/v1/agents, /api/v1/agents/{id}	agent_registry
iw-agent-runtime	Agent execution & orchestration	/api/v1/agents/{id}/execute, /api/v1/agents/{id}/sessions	agent_sessions, agent_invocations
continuity	Agent memory & state persistence	/api/v1/agents/{id}/memory, /api/v1/continuity	memory_entries, continuity_ledger
twin-orchestrator	Workflow orchestration & approval routing	/api/v1/workflows, /api/v1/workspace/governance/approvals	proposals, approvals, execution_log
pipeline	Pipeline definition & versioning	/api/v1/pipelines, /api/v1/pipelines/{id}	pipeline_definitions, pipeline_versions
loader	Data loading & transformation	/api/v1/pipelines/{id}/test	loader_configurations
knowledge	Document indexing & semantic search	/api/v1/knowledge, /api/v1/knowledge/search	documents, knowledge_articles
intelligence	Semantic capabilities & reasoning	/api/v1/capabilities, /api/v1/workspace/discovery	capability_registry, semantic_index
spine	Immutable event log & relationships	/api/v1/workspace/spine, /api/v1/entity/{id}/versions	entity_spine, spine_relationships, entity_versions
telemetry	Metrics collection & reporting	/api/v1/telemetry, /api/v1/signals	usage_rollups, metric_events
signals	Real-time event streaming	WebSocket or /api/v1/signals	signal_events
hermes	Approval workflow & notifications	/api/v1/workspace/governance/approvals	approval_history
task-management	Task assignment & tracking	/api/v1/workflows/my-tasks	task_assignments, task_history
marketplace-installation	Plugin/connector installation	/api/v1/marketplace/install, /api/v1/marketplace/installed	marketplace_installations
billing	Tenant billing & entitlements	/api/v1/tenants/{id}/billing	subscriptions, usage_charges

SERVICES NOT CONSUMED BY PLATFORM

These are internal/cross-service dependencies:

Service	Role	Why Not Platform
context-fetch	Context enrichment for agents	Called by agents/services, not UI
schema-ai	AI-powered schema inference	Backend utility for workbench (piped through pipeline)
folder-watcher	File system monitoring	Internal service integration
webhook-ingress	External webhook receiver	Receives payloads, triggers events
vercel-mcp	Vercel-specific MCP server	Provider-specific connector
agent-registry	Internal agent catalog	Consumed via mcp-pool + intelligence

STORAGE LAYER ISOLATION

Platform Never Talks To Storage Directly

❌ Platform does NOT:
  - Import Neon or D1 drivers
  - Execute SQL directly
  - Access KV/Redis
  - Read from R2

✅ Platform ALWAYS:
  - fetch(/api/v1/*)
  - Gateway validates + routes
  - Service owns queries
  - Returns typed JSON

ENVIRONMENT VARIABLES

Platform requires:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY (Clerk auth)
CLERK_SECRET_KEY (Clerk backend)
NEXT_PUBLIC_API_BASE (API gateway URL, default /api/v1)

Backend shared:

NEON_DATABASE_URL (control plane Postgres)
TURSO_CONNECTION_URL (D1 compatible endpoint)
UPSTASH_REDIS_URL (pub/sub + caching)
TURSO_AUTH_TOKEN (D1 auth)

DEPLOYMENT ARCHITECTURE

Vercel (Frontend)
  └── apps/platform (Next.js on Vercel Serverless)

Cloudflare Workers (Backend)
  ├── gateway (routing)
  ├── tenants (auth)
  ├── admin (users)
  ├── connector (metadata)
  ├── connector-sync (sync)
  ├── integration-management-mcp (OAuth)
  ├── provider-management-mcp (registry)
  ├── mcp-pool (tool registry)
  ├── mcp-connector (tool invocation)
  ├── agent-registry (agents)
  ├── iw-agent-runtime (execution)
  ├── continuity (memory)
  ├── twin-orchestrator (workflows)
  ├── pipeline (definitions)
  ├── loader (transforms)
  ├── knowledge (semantic search)
  ├── intelligence (reasoning)
  ├── spine (events)
  ├── telemetry (metrics)
  ├── signals (streaming)
  ├── hermes (approvals)
  ├── task-management (tasks)
  ├── marketplace-installation (plugins)
  └── billing (subscriptions)

Storage Layer
  ├── Neon (Postgres) - Tenants, control plane
  ├── Turso/D1 (SQLite) - Runtime, tenant data
  ├── Upstash (Redis) - Cache, pub/sub
  └── R2 (Cloudflare) - Artifacts, documents

INTEGRATION CHECKLIST FOR NEW PAGES

When adding a new page to Platform:

Define Page Route → app/(shell)/[name]/page.tsx
Create Component → components/[Name]Page.tsx
Identify Services → Which services own the data?
Map APIs → Which /api/v1/* endpoints?
Create SWR Hook → lib/hooks/use[Data].ts
Add to Navigation → Update shell layout
Test Auth → Does Clerk middleware block unauth?
Test SWR → Does cache invalidate on mutation?
Test Error States → Network failure, auth timeout
Update admin-data.ts → Add to capability registry

QUICK REFERENCE: SERVICE TO PAGE MAPPING

Pages	Services	APIs
Dashboard	tenants, admin	/auth/session
Workspace	spine, intelligence, gateway	/workspace/discovery
Connectors	connector, connector-sync, integration-management-mcp	/connectors, /connections
Marketplace	marketplace-installation, provider-management-mcp	/marketplace/items, /marketplace/install
Network/MCP	mcp-pool, intelligence	/connectors/mcp-pool, /capabilities
Network	spine, telemetry, signals	/workspace/topology, /signals
Agents	agent-registry, iw-agent-runtime, continuity	/agents, /agents/{id}/memory
Approvals	twin-orchestrator, hermes, admin	/workspace/governance/approvals
Governance	twin-orchestrator, admin	/workspace/governance, /workspace/governance/policies
My Work	task-management, workflow, intelligence	/workflows/my-tasks
Communications	signals, telemetry	/signals, /telemetry
Settings	admin, tenants, integration-management-mcp	/workspace/config, /keys
Workbench	pipeline, loader, schema-ai, intelligence	/pipelines, /pipelines/{id}/test

CRITICAL BOUNDARIES

Frontend / Backend Split

Frontend owns:

UI state (open/closed, active tab, form input)
Presentation (theming, animations, layout)
Client-side navigation

Backend owns:

Business logic (validation, auth, permissions)
Data truth (D1 tables, Spine events, Neon rows)
Cross-system coordination

Gateway Responsibility

The Gateway service is the only API entry point for Platform:

Platform Request
  ↓
Gateway (in services/gateway)
  ├── Validate Clerk JWT
  ├── Resolve tenant context
  ├── Check permissions
  ├── Route to service
  └── Return 401/403 if denied

No Platform component should bypass Gateway.

TESTING STRATEGY

Unit Tests

Component rendering (React Testing Library)
SWR hook behavior (mock fetch)
Form validation

Integration Tests

SWR cache invalidation on mutation
Error boundary handling
Auth flow with Clerk

E2E Tests

Full user journeys (Cypress/Playwright)
Multi-page workflows
Real backend service interactions

PERFORMANCE CHECKLIST

SWR hooks use shouldRetryOnError: false for intentional errors
Connectors page virtualizes large lists (content-visibility)
Agent memory doesn't load entire history (pagination)
Marketplace uses bundle-dynamic-imports for heavy modals
Dashboard preloads next page on hover (bundle-preload)
No N+1 queries in API routes (use Promise.all)
Spine events deduplicated with React.cache()

AUDIT TRAIL

Date	Change	Author
2026-08-06	Initial audit: 32 services, 14 platform pages	v0
-	Mapped all /api/v1/* routes	-
-	Documented golden loop & storage isolation	-
-	Created service-to-page matrix	-

NEXT STEPS

High Priority

Verify all 32 services have corresponding API routes documented
Add real-time WebSocket support for signals (live agent status)
Implement full audit trail UI for governance page

Medium Priority

Add search/filter to connectors, agents, marketplace
Create dashboard widgets library (charts, metrics)
Implement workflow builder advanced features

Low Priority

Mobile responsive UI refinements
Accessibility audit (WCAG 2.1 AA)
Performance profiling & optimization

Generated by v0
For questions: Refer to integratewise-live monorepo docs

Complete Frontend-to-Backend Architecture Audit

PLATFORM OVERVIEW

CORE RULE

GOLDEN LOOP

ENTRY & AUTH LAYER

Auth Flow

PLATFORM PAGES & SERVICE MAPPING

1. Dashboard (/)

2. Workspace (/workspace)

3. Connectors (/connectors)

4. Marketplace (/marketplace)

5. Network - MCP (/network/mcp)

6. Network - General (/network)

7. Agents (/agents)

8. Approvals (/approvals)

9. Governance (/governance)

10. My Work (/my-work)

11. Communications (/communications)

12. Settings (/settings)

13. Workbench (/workbench)

14. Control Surface (/control/[surface])

API CLIENT LAYER

lib/api-client.ts

COMPONENT ARCHITECTURE

Platform Shell Layout

Reusable Components

DATA FLOW PATTERNS

Pattern 1: Fetch-on-Load + Cache

Pattern 2: User Action + Mutation

Pattern 3: Real-Time Updates

BACKEND SERVICES DIRECT TO PLATFORM

Core Services (✓ Platform Consumes)

SERVICES NOT CONSUMED BY PLATFORM

STORAGE LAYER ISOLATION

Platform Never Talks To Storage Directly

ENVIRONMENT VARIABLES

DEPLOYMENT ARCHITECTURE

INTEGRATION CHECKLIST FOR NEW PAGES

QUICK REFERENCE: SERVICE TO PAGE MAPPING

CRITICAL BOUNDARIES

Frontend / Backend Split

Gateway Responsibility

TESTING STRATEGY

Unit Tests

Integration Tests

E2E Tests

PERFORMANCE CHECKLIST

AUDIT TRAIL

NEXT STEPS

High Priority

Medium Priority

Low Priority

1. Dashboard (`/`)

2. Workspace (`/workspace`)

3. Connectors (`/connectors`)

4. Marketplace (`/marketplace`)

5. Network - MCP (`/network/mcp`)

6. Network - General (`/network`)

7. Agents (`/agents`)

8. Approvals (`/approvals`)

9. Governance (`/governance`)

10. My Work (`/my-work`)

11. Communications (`/communications`)

12. Settings (`/settings`)

13. Workbench (`/workbench`)

14. Control Surface (`/control/[surface]`)

`lib/api-client.ts`