{"slug":"architecture/PLATFORM_BACKEND_MAP","title":"IntegrateWise Platform → Backend Services Map","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/PLATFORM_BACKEND_MAP.mdx","bytes":25836,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## Complete Frontend-to-Backend Architecture Audit\n\n**Generated**: August 6, 2026  \n**Scope**: apps/platform only (management console UI)  \n**Status**: Production Ready\n\n---\n\n## PLATFORM OVERVIEW\n\n**Location**: `apps/platform`  \n**Type**: Next.js 16 App Router (React 19)  \n**Role**: Operational Control Plane UI for tenant/connector/capability management  \n**Auth**: Clerk (email + password, OAuth ready)  \n**API Surface**: `/api/v1/*` (fronted by Gateway service)\n\n---\n\n## CORE RULE\n\n- **Platform UI never owns truth** — all state lives in backend D1/Neon\n- **Platform UI never talks directly to storage** — routes through `/api/v1` only\n- **Platform UI consumes governed APIs** — no auth bypass\n- **Backend services own capability** — business logic is service-owned\n- **Spine owns operational state** — immutable event log\n- **Neon owns control plane** — tenants, orgs, subscriptions, entitlements\n- **D1 operates tenant runtime** — entity registry, policies, capabilities\n\n---\n\n## GOLDEN LOOP\n\n```\nUser Action\n    ↓\nPlatform UI Component\n    ↓\nfetch(/api/v1/*)\n    ↓\nGateway (validation, auth, routing)\n    ↓\nBackend Service (business logic)\n    ↓\nD1 / Neon / Spine (truth)\n    ↓\nEvent Emitted\n    ↓\nProjection Updated\n    ↓\nPlatform UI Re-renders (SWR cache refresh)\n```\n\n---\n\n## ENTRY & AUTH LAYER\n\n### Auth Flow\n\n```\nPlatform URL\n    ↓\nClerk Session Check (middleware)\n    ↓\nSession Valid?\n    ├─ YES → Resolve tenant context → Dashboard\n    └─ NO → /login (Clerk)\n```\n\n**Session Endpoints**\n\n- `GET /api/v1/auth/session` → `services/tenants` + `services/admin`\n  - Returns: `{ user, tenant, permissions, role }`\n  - SWR Hook: `useSession()`\n\n**Key Management**\n\n- `GET /api/v1/keys` → `services/admin`\n  - Returns: `{ apiKeys[], secrets[] }`\n  - SWR Hook: `useKeys()`\n\n---\n\n## PLATFORM PAGES & SERVICE MAPPING\n\n### 1. Dashboard (`/`)\n\n**Component**: `app/(shell)/page.tsx`  \n**Role**: Entry point, operational summary\n\n**Displays**:\n\n- Tenant overview\n- Recent activity\n- Key metrics\n\n**Services**: `tenants`, `admin`  \n**APIs**: None (static initial render, SWR populates later)\n\n---\n\n### 2. Workspace (`/workspace`)\n\n**Component**: `app/(shell)/workspace/page.tsx`  \n**Role**: Central discovery and workspace state\n\n**Displays**:\n\n- Workspace topology\n- Connected systems\n- Capability registry\n\n**Services**: `spine`, `intelligence`, `gateway`  \n**APIs**:\n\n- `GET /api/v1/workspace/discovery` → workspace state projection\n- `GET /api/v1/workspace/bootstrap` → initial workspace load\n\n**Data Flow**:\n\n```\nuseWorkspaceDiscovery()\n    ↓\nfetch(/api/v1/workspace/discovery)\n    ↓\nGateway → Intelligence Service\n    ↓\nD1: workspace_metadata, entity_registry, capability_registry\n    ↓\nSWR Cache → Component re-renders\n```\n\n---\n\n### 3. Connectors (`/connectors`)\n\n**Component**: `app/(shell)/connectors/page.tsx`  \n**Role**: Connector lifecycle & management\n\n**Displays**:\n\n- Installed connectors\n- Connection status\n- Sync configuration\n- Health metrics\n\n**Services**: `connector`, `connector-sync`, `integration-management-mcp`, `provider-management-mcp`  \n**APIs**:\n\n- `GET /api/v1/connectors` → catalog of connectors\n- `POST /api/v1/connectors/{id}/activate` → install connector\n- `DELETE /api/v1/connectors/{id}` → remove connector\n- `GET /api/v1/connections` → active connections\n- `POST /api/v1/connections` → create connection\n- `PATCH /api/v1/connections/{id}` → update connection\n\n**Connectors Tracked**:\n\n- Hubspot (CRM)\n- Salesforce (CRM)\n- Pipedrive (CRM)\n- Nango (integration broker)\n- Zapier (automation)\n- Custom (user-built)\n\n**Data Storage**:\n\n```\nD1 Tables:\n  - connector_catalog (metadata)\n  - tenant_connections (state)\n  - entity_sync_state (sync progress)\n  - capability_registry (exposed tools)\n```\n\n---\n\n### 4. Marketplace (`/marketplace`)\n\n**Component**: `app/(shell)/marketplace/page.tsx`  \n**Role**: Plugin/MCP/connector discovery\n\n**Displays**:\n\n- Available connectors\n- MCP servers\n- Plugins\n- Installation status\n\n**Services**: `marketplace-installation`, `provider-management-mcp`, `integration-management-mcp`  \n**APIs**:\n\n- `GET /api/v1/workspace/marketplace-items` → available items\n- `POST /api/v1/marketplace/install/{id}` → install item\n- `GET /api/v1/marketplace/installed` → installed items\n- `DELETE /api/v1/marketplace/{id}` → uninstall\n\n---\n\n### 5. Network - MCP (`/network/mcp`)\n\n**Component**: `app/(shell)/network/mcp/page.tsx`  \n**Role**: MCP server registry & tool exposure\n\n**Displays**:\n\n- Registered MCP servers\n- Exposed tools\n- Semantic capabilities\n- Tool permissions\n\n**Services**: `mcp-pool`, `mcp-connector`, `provider-management-mcp`, `intelligence`  \n**APIs**:\n\n- `GET /api/v1/connectors/mcp-pool` → MCP registry\n- `POST /api/v1/connectors/mcp-pool/register` → register server\n- `GET /api/v1/capabilities` → semantic tool registry\n- `PATCH /api/v1/capabilities/{id}/permissions` → manage access\n\n**Data Storage**:\n\n```\nD1 Tables:\n  - mcp_bindings (MCP ↔ workspace mapping)\n  - capability_registry (tool metadata)\n  - capability_grants (permissions)\n```\n\n---\n\n### 6. Network - General (`/network`)\n\n**Component**: `app/(shell)/network/page.tsx`  \n**Role**: Topology & system integration\n\n**Displays**:\n\n- Service health\n- Integration topology\n- Capability graph\n- Data flow diagram\n\n**Services**: `spine`, `intelligence`, `telemetry`, `signals`  \n**APIs**:\n\n- `GET /api/v1/workspace/topology` → system graph\n- `GET /api/v1/signals` → real-time metrics\n\n---\n\n### 7. Agents (`/agents`)\n\n**Component**: `app/(shell)/agents/page.tsx`  \n**Role**: Agent lifecycle & orchestration\n\n**Displays**:\n\n- Deployed agents\n- Agent status\n- Memory state\n- Execution logs\n\n**Services**: `agent-registry`, `iw-agent-runtime`, `continuity`, `twin-orchestrator`  \n**APIs**:\n\n- `GET /api/v1/agents` → agent catalog\n- `POST /api/v1/agents` → create agent\n- `PATCH /api/v1/agents/{id}` → update config\n- `GET /api/v1/agents/{id}/memory` → agent state\n- `GET /api/v1/agents/{id}/sessions` → execution history\n\n**Data Storage**:\n\n```\nD1 Tables:\n  - agent_registry (agent metadata)\n  - agent_sessions (execution state)\n  - memory_entries (agent continuity)\n  - continuity_ledger (event log)\n```\n\n---\n\n### 8. Approvals (`/approvals`)\n\n**Component**: `app/(shell)/approvals/page.tsx`  \n**Role**: Governance & workflow approvals\n\n**Displays**:\n\n- Pending approvals\n- Approval history\n- Policy audit trail\n- Execution control\n\n**Services**: `twin-orchestrator`, `hermes`, `admin`  \n**APIs**:\n\n- `GET /api/v1/workspace/governance/approvals` → pending items\n- `POST /api/v1/workspace/governance/approvals/{id}/approve` → approve\n- `POST /api/v1/workspace/governance/approvals/{id}/reject` → reject\n- `GET /api/v1/workspace/governance/policies` → policy registry\n\n**Data Storage**:\n\n```\nD1 Tables:\n  - proposals (pending approvals)\n  - approvals (approval decisions)\n  - audit_events (governance log)\n  - policies (policy registry)\n```\n\n---\n\n### 9. Governance (`/governance`)\n\n**Component**: `app/(shell)/governance/page.tsx`  \n**Role**: Policy & access control\n\n**Displays**:\n\n- Policy rules\n- Role-based access\n- Data governance\n- Compliance state\n\n**Services**: `twin-orchestrator`, `admin`, `intelligence`  \n**APIs**:\n\n- `GET /api/v1/workspace/governance` → policy state\n- `POST /api/v1/workspace/governance/policies` → create policy\n- `PATCH /api/v1/workspace/governance/policies/{id}` → update policy\n- `GET /api/v1/workspace/governance/audit` → audit log\n\n---\n\n### 10. My Work (`/my-work`)\n\n**Component**: `app/(shell)/my-work/page.tsx`  \n**Role**: User task dashboard\n\n**Displays**:\n\n- Assigned tasks\n- My workflows\n- Recent activity\n- Metrics dashboard\n\n**Services**: `task-management`, `workflow`, `intelligence`  \n**APIs**:\n\n- `GET /api/v1/workflows/my-tasks` → assigned work\n- `GET /api/v1/workflows/recent` → recent workflows\n- `GET /api/v1/telemetry/personal` → user metrics\n\n---\n\n### 11. Communications (`/communications`)\n\n**Component**: `app/(shell)/communications/page.tsx`  \n**Role**: Alerts & notifications\n\n**Displays**:\n\n- System alerts\n- Integration notifications\n- Error logs\n- Event stream\n\n**Services**: `signals`, `telemetry`, `webhook-ingress`  \n**APIs**:\n\n- `GET /api/v1/signals` → real-time events\n- `GET /api/v1/telemetry` → metrics\n- `GET /api/v1/workspace/audit` → audit events\n\n---\n\n### 12. Settings (`/settings`)\n\n**Component**: `app/(shell)/settings/page.tsx`  \n**Role**: Configuration & preferences\n\n**Displays**:\n\n- Workspace settings\n- User preferences\n- Integration config\n- API keys & secrets\n\n**Services**: `admin`, `tenants`, `integration-management-mcp`  \n**APIs**:\n\n- `GET /api/v1/workspace/config` → workspace settings\n- `PATCH /api/v1/workspace/config` → update settings\n- `GET /api/v1/keys` → API key management\n- `POST /api/v1/keys` → create key\n- `DELETE /api/v1/keys/{id}` → revoke key\n\n---\n\n### 13. Workbench (`/workbench`)\n\n**Component**: `app/(shell)/workbench/page.tsx`  \n**Role**: Low-code builder & testing\n\n**Displays**:\n\n- Workflow builder\n- Schema editor\n- Test runner\n- Capability explorer\n\n**Services**: `pipeline`, `loader`, `schema-ai`, `intelligence`  \n**APIs**:\n\n- `GET /api/v1/pipelines` → pipeline catalog\n- `POST /api/v1/pipelines` → create pipeline\n- `POST /api/v1/pipelines/{id}/test` → test execution\n- `GET /api/v1/schema` → schema registry\n\n---\n\n### 14. Control Surface (`/control/[surface]`)\n\n**Component**: `app/(shell)/control/[surface]/page.tsx`  \n**Role**: Dynamic control panels\n\n**Displays**:\n\n- Runtime controls\n- System administration\n- Performance tuning\n- Deployment config\n\n**Services**: `admin`, `tenants`, `gateway`  \n**APIs**:\n\n- `GET /api/v1/deployment/config` → deployment state\n- `PATCH /api/v1/deployment/config` → update deployment\n- `GET /api/v1/runtime/metrics` → runtime metrics\n\n---\n\n## API CLIENT LAYER\n\n### `lib/api-client.ts`\n\n**SWR Fetchers** (automatic caching & request deduplication):\n\n```typescript\n// Authentication\nuseSession() → GET /api/v1/auth/session\nuseKeys() → GET /api/v1/keys\n\n// Connections & Integrations\nuseConnections() → GET /api/v1/connections\nuseConnectorProjections() → GET /api/v1/connectors\n\n// Workspace Discovery\nuseWorkspaceDiscovery(skip?) → GET /api/v1/workspace/discovery\n  - Returns canonical workspace projection\n  - Skips fetch until session confirmed (conditional SWR)\n```\n\n**Direct Fetch Helpers**:\n\n```typescript\nrequest<T>(path, options?) → authenticated fetch to /api/v1{path}\n  - Auto-attaches auth headers\n  - Returns typed JSON\n  - Throws on auth failure\n```\n\n---\n\n## COMPONENT ARCHITECTURE\n\n### Platform Shell Layout\n\n```\napp/(shell)/layout.tsx\n  ├── Navbar (with tenant selector, user menu)\n  ├── Sidebar (navigation)\n  ├── TenantProvider (context)\n  └── Page Routes\n      ├── /\n      ├── /workspace\n      ├── /connectors\n      ├── /marketplace\n      ├── /network/mcp\n      ├── /network\n      ├── /agents\n      ├── /approvals\n      ├── /governance\n      ├── /my-work\n      ├── /communications\n      ├── /settings\n      └── /workbench\n```\n\n### Reusable Components\n\n- **ConnectorCard**: Display connector + status\n- **CapabilityGrid**: Tool registry visualization\n- **AgentPanel**: Agent state display\n- **PolicyEditor**: Governance rule builder\n- **WorkflowBuilder**: Low-code editor\n\n---\n\n## DATA FLOW PATTERNS\n\n### Pattern 1: Fetch-on-Load + Cache\n\n```\nComponent Mount\n  ↓\nSWR Hook (useSWR)\n  ↓\nfetch(/api/v1/*)\n  ↓\nGateway validates auth + routes\n  ↓\nService fetches from D1\n  ↓\nResponse cached in SWR\n  ↓\nComponent renders (sync)\n```\n\n### Pattern 2: User Action + Mutation\n\n```\nUser clicks button\n  ↓\nForm submission / Event handler\n  ↓\nfetch(POST /api/v1/*, { body })\n  ↓\nGateway routes to service\n  ↓\nService validates + stores in D1\n  ↓\nEvent emitted (D1 → Redis Pub/Sub)\n  ↓\nSWR cache invalidated (mutate)\n  ↓\nComponent refetches & re-renders\n```\n\n### Pattern 3: Real-Time Updates\n\n```\nWebhook received (from external system)\n  ↓\nwebhook-ingress service\n  ↓\nEvent stored in D1 + Spine\n  ↓\nProjection updated\n  ↓\nWebSocket broadcast (if enabled)\n  ↓\nPlatform UI subscribes + updates\n```\n\n---\n\n## BACKEND SERVICES DIRECT TO PLATFORM\n\n### Core Services (✓ Platform Consumes)\n\n| Service                        | Role                                             | APIs                                                       | D1 Tables                                          |\n| ------------------------------ | ------------------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------- |\n| **gateway**                    | Request routing, auth validation, tenant binding | All /api/v1/\\* routes                                      | -                                                  |\n| **tenants**                    | Tenant lifecycle, provisioning, context          | /api/v1/auth/session, /api/v1/tenants                      | tenants, organizations, subscriptions              |\n| **admin**                      | User, role, permission management                | /api/v1/keys, /api/v1/users, /api/v1/roles                 | users, memberships, roles, permissions             |\n| **connector**                  | Connector activation, state                      | /api/v1/connectors, /api/v1/connectors/{id}                | connector_catalog, tenant_connections              |\n| **connector-sync**             | Sync orchestration, state tracking               | /api/v1/connections, /api/v1/connectors/sync               | entity_sync_state, sync_history                    |\n| **integration-management-mcp** | Connector metadata, OAuth flows                  | /api/v1/connections/oauth, /api/v1/marketplace/connectors  | integration_catalog, oauth_state                   |\n| **provider-management-mcp**    | Provider registry, capability exposure           | /api/v1/capabilities, /api/v1/connectors/providers         | capability_registry, provider_catalog              |\n| **mcp-pool**                   | MCP server registry & management                 | /api/v1/connectors/mcp-pool, /api/v1/capabilities          | mcp_bindings, capability_registry                  |\n| **mcp-connector**              | MCP tool invocation                              | /api/v1/connectors/mcp-pool/invoke                         | tool_invocations                                   |\n| **agent-registry**             | Agent metadata & lifecycle                       | /api/v1/agents, /api/v1/agents/{id}                        | agent_registry                                     |\n| **iw-agent-runtime**           | Agent execution & orchestration                  | /api/v1/agents/{id}/execute, /api/v1/agents/{id}/sessions  | agent_sessions, agent_invocations                  |\n| **continuity**                 | Agent memory & state persistence                 | /api/v1/agents/{id}/memory, /api/v1/continuity             | memory_entries, continuity_ledger                  |\n| **twin-orchestrator**          | Workflow orchestration & approval routing        | /api/v1/workflows, /api/v1/workspace/governance/approvals  | proposals, approvals, execution_log                |\n| **pipeline**                   | Pipeline definition & versioning                 | /api/v1/pipelines, /api/v1/pipelines/{id}                  | pipeline_definitions, pipeline_versions            |\n| **loader**                     | Data loading & transformation                    | /api/v1/pipelines/{id}/test                                | loader_configurations                              |\n| **knowledge**                  | Document indexing & semantic search              | /api/v1/knowledge, /api/v1/knowledge/search                | documents, knowledge_articles                      |\n| **intelligence**               | Semantic capabilities & reasoning                | /api/v1/capabilities, /api/v1/workspace/discovery          | capability_registry, semantic_index                |\n| **spine**                      | Immutable event log & relationships              | /api/v1/workspace/spine, /api/v1/entity/{id}/versions      | entity_spine, spine_relationships, entity_versions |\n| **telemetry**                  | Metrics collection & reporting                   | /api/v1/telemetry, /api/v1/signals                         | usage_rollups, metric_events                       |\n| **signals**                    | Real-time event streaming                        | WebSocket or /api/v1/signals                               | signal_events                                      |\n| **hermes**                     | Approval workflow & notifications                | /api/v1/workspace/governance/approvals                     | approval_history                                   |\n| **task-management**            | Task assignment & tracking                       | /api/v1/workflows/my-tasks                                 | task_assignments, task_history                     |\n| **marketplace-installation**   | Plugin/connector installation                    | /api/v1/marketplace/install, /api/v1/marketplace/installed | marketplace_installations                          |\n| **billing**                    | Tenant billing & entitlements                    | /api/v1/tenants/{id}/billing                               | subscriptions, usage_charges                       |\n\n---\n\n## SERVICES NOT CONSUMED BY PLATFORM\n\nThese are internal/cross-service dependencies:\n\n| Service             | Role                          | Why Not Platform                                       |\n| ------------------- | ----------------------------- | ------------------------------------------------------ |\n| **context-fetch**   | Context enrichment for agents | Called by agents/services, not UI                      |\n| **schema-ai**       | AI-powered schema inference   | Backend utility for workbench (piped through pipeline) |\n| **folder-watcher**  | File system monitoring        | Internal service integration                           |\n| **webhook-ingress** | External webhook receiver     | Receives payloads, triggers events                     |\n| **vercel-mcp**      | Vercel-specific MCP server    | Provider-specific connector                            |\n| **agent-registry**  | Internal agent catalog        | Consumed via mcp-pool + intelligence                   |\n\n---\n\n## STORAGE LAYER ISOLATION\n\n### Platform Never Talks To Storage Directly\n\n```\n❌ Platform does NOT:\n  - Import Neon or D1 drivers\n  - Execute SQL directly\n  - Access KV/Redis\n  - Read from R2\n\n✅ Platform ALWAYS:\n  - fetch(/api/v1/*)\n  - Gateway validates + routes\n  - Service owns queries\n  - Returns typed JSON\n```\n\n---\n\n## ENVIRONMENT VARIABLES\n\n**Platform requires**:\n\n- `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` (Clerk auth)\n- `CLERK_SECRET_KEY` (Clerk backend)\n- `NEXT_PUBLIC_API_BASE` (API gateway URL, default `/api/v1`)\n\n**Backend shared**:\n\n- `NEON_DATABASE_URL` (control plane Postgres)\n- `TURSO_CONNECTION_URL` (D1 compatible endpoint)\n- `UPSTASH_REDIS_URL` (pub/sub + caching)\n- `TURSO_AUTH_TOKEN` (D1 auth)\n\n---\n\n## DEPLOYMENT ARCHITECTURE\n\n```\nVercel (Frontend)\n  └── apps/platform (Next.js on Vercel Serverless)\n\nCloudflare Workers (Backend)\n  ├── gateway (routing)\n  ├── tenants (auth)\n  ├── admin (users)\n  ├── connector (metadata)\n  ├── connector-sync (sync)\n  ├── integration-management-mcp (OAuth)\n  ├── provider-management-mcp (registry)\n  ├── mcp-pool (tool registry)\n  ├── mcp-connector (tool invocation)\n  ├── agent-registry (agents)\n  ├── iw-agent-runtime (execution)\n  ├── continuity (memory)\n  ├── twin-orchestrator (workflows)\n  ├── pipeline (definitions)\n  ├── loader (transforms)\n  ├── knowledge (semantic search)\n  ├── intelligence (reasoning)\n  ├── spine (events)\n  ├── telemetry (metrics)\n  ├── signals (streaming)\n  ├── hermes (approvals)\n  ├── task-management (tasks)\n  ├── marketplace-installation (plugins)\n  └── billing (subscriptions)\n\nStorage Layer\n  ├── Neon (Postgres) - Tenants, control plane\n  ├── Turso/D1 (SQLite) - Runtime, tenant data\n  ├── Upstash (Redis) - Cache, pub/sub\n  └── R2 (Cloudflare) - Artifacts, documents\n```\n\n---\n\n## INTEGRATION CHECKLIST FOR NEW PAGES\n\nWhen adding a new page to Platform:\n\n1. **Define Page Route** → `app/(shell)/[name]/page.tsx`\n2. **Create Component** → `components/[Name]Page.tsx`\n3. **Identify Services** → Which services own the data?\n4. **Map APIs** → Which `/api/v1/*` endpoints?\n5. **Create SWR Hook** → `lib/hooks/use[Data].ts`\n6. **Add to Navigation** → Update shell layout\n7. **Test Auth** → Does Clerk middleware block unauth?\n8. **Test SWR** → Does cache invalidate on mutation?\n9. **Test Error States** → Network failure, auth timeout\n10. **Update admin-data.ts** → Add to capability registry\n\n---\n\n## QUICK REFERENCE: SERVICE TO PAGE MAPPING\n\n| Pages          | Services                                              | APIs                                                  |\n| -------------- | ----------------------------------------------------- | ----------------------------------------------------- |\n| Dashboard      | tenants, admin                                        | /auth/session                                         |\n| Workspace      | spine, intelligence, gateway                          | /workspace/discovery                                  |\n| Connectors     | connector, connector-sync, integration-management-mcp | /connectors, /connections                             |\n| Marketplace    | marketplace-installation, provider-management-mcp     | /marketplace/items, /marketplace/install              |\n| Network/MCP    | mcp-pool, intelligence                                | /connectors/mcp-pool, /capabilities                   |\n| Network        | spine, telemetry, signals                             | /workspace/topology, /signals                         |\n| Agents         | agent-registry, iw-agent-runtime, continuity          | /agents, /agents/{id}/memory                          |\n| Approvals      | twin-orchestrator, hermes, admin                      | /workspace/governance/approvals                       |\n| Governance     | twin-orchestrator, admin                              | /workspace/governance, /workspace/governance/policies |\n| My Work        | task-management, workflow, intelligence               | /workflows/my-tasks                                   |\n| Communications | signals, telemetry                                    | /signals, /telemetry                                  |\n| Settings       | admin, tenants, integration-management-mcp            | /workspace/config, /keys                              |\n| Workbench      | pipeline, loader, schema-ai, intelligence             | /pipelines, /pipelines/{id}/test                      |\n\n---\n\n## CRITICAL BOUNDARIES\n\n### Frontend / Backend Split\n\n**Frontend owns**:\n\n- UI state (open/closed, active tab, form input)\n- Presentation (theming, animations, layout)\n- Client-side navigation\n\n**Backend owns**:\n\n- Business logic (validation, auth, permissions)\n- Data truth (D1 tables, Spine events, Neon rows)\n- Cross-system coordination\n\n### Gateway Responsibility\n\nThe Gateway service is the **only** API entry point for Platform:\n\n```\nPlatform Request\n  ↓\nGateway (in services/gateway)\n  ├── Validate Clerk JWT\n  ├── Resolve tenant context\n  ├── Check permissions\n  ├── Route to service\n  └── Return 401/403 if denied\n```\n\nNo Platform component should bypass Gateway.\n\n---\n\n## TESTING STRATEGY\n\n### Unit Tests\n\n- Component rendering (React Testing Library)\n- SWR hook behavior (mock fetch)\n- Form validation\n\n### Integration Tests\n\n- SWR cache invalidation on mutation\n- Error boundary handling\n- Auth flow with Clerk\n\n### E2E Tests\n\n- Full user journeys (Cypress/Playwright)\n- Multi-page workflows\n- Real backend service interactions\n\n---\n\n## PERFORMANCE CHECKLIST\n\n- [ ] SWR hooks use `shouldRetryOnError: false` for intentional errors\n- [ ] Connectors page virtualizes large lists (content-visibility)\n- [ ] Agent memory doesn't load entire history (pagination)\n- [ ] Marketplace uses `bundle-dynamic-imports` for heavy modals\n- [ ] Dashboard preloads next page on hover (`bundle-preload`)\n- [ ] No N+1 queries in API routes (use Promise.all)\n- [ ] Spine events deduplicated with `React.cache()`\n\n---\n\n## AUDIT TRAIL\n\n| Date       | Change                                        | Author |\n| ---------- | --------------------------------------------- | ------ |\n| 2026-08-06 | Initial audit: 32 services, 14 platform pages | v0     |\n| -          | Mapped all /api/v1/\\* routes                  | -      |\n| -          | Documented golden loop & storage isolation    | -      |\n| -          | Created service-to-page matrix                | -      |\n\n---\n\n## NEXT STEPS\n\n### High Priority\n\n1. Verify all 32 services have corresponding API routes documented\n2. Add real-time WebSocket support for signals (live agent status)\n3. Implement full audit trail UI for governance page\n\n### Medium Priority\n\n4. Add search/filter to connectors, agents, marketplace\n5. Create dashboard widgets library (charts, metrics)\n6. Implement workflow builder advanced features\n\n### Low Priority\n\n7. Mobile responsive UI refinements\n8. Accessibility audit (WCAG 2.1 AA)\n9. Performance profiling & optimization\n\n---\n\nGenerated by v0  \nFor questions: Refer to integratewise-live monorepo docs\n"}