{"slug":"architecture/CONTEXT_TRANSFER_PLATFORM_UI","title":"Context Transfer: Universal Layer → Platform UI","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/CONTEXT_TRANSFER_PLATFORM_UI.mdx","bytes":18617,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## Overview\n\nThis document transfers all architectural context needed to build the **IntegrateWise Platform UI** (`apps/platform`) as a privileged consumer of the **Universal One Access Network** (`apps/one-access`).\n\n---\n\n## 1. The Five Agents (Tenant Spine Schema)\n\nDefined in `packages/spine-schema/src/tenant-schema.ts`:\n\n| Agent                   | Type                  | Operates On                                                       | Modifies                                                     |\n| ----------------------- | --------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------ |\n| **Twin Orchestrator**   | `twin-orchestrator`   | context, memory, relationships, proposals, approvals              | context, proposals, orchestration-plans                      |\n| **Schema Generator**    | `schema-generator`    | source-schemas, tenant-context, business-knowledge                | tenant-schema, field-mappings, transforms                    |\n| **Schema Orchestrator** | `schema-orchestrator` | tenant-schema, schema-mappings, source-changes                    | schema-mappings, mapping-status, sync-triggers               |\n| **Adaptive Auto-Tuner** | `adaptive-auto-tuner` | performance-metrics, execution-patterns, kpi-trends, cost-metrics | tuning-parameters, resource-allocation, execution-strategies |\n| **Co-Worker**           | `co-worker`           | tasks, actions, executions                                        | tasks, actions, executions                                   |\n| **Triage**              | `triage`              | signals, intents, priorities                                      | priorities, assignments                                      |\n\n**Platform UI must surface all 6 agent types** in the agents management page.\n\n---\n\n## 2. Universal One Access Network (Host-Neutral Layer)\n\n`apps/one-access` provides universal APIs consumed by ALL hosts:\n\n### Universal Routes\n\n```\n/auth              → Universal identity, tenant, consent, delegation, client authorization\n/marketplace       → Universal catalog (connectors, MCP, plugins, agents, models, templates)\n/connectors        → Universal connection & authorization management\n/discovery         → Universal discovery (hosts, tools, schemas, capabilities, connections)\n/capability-matrix → Effective-access view (hosts, roles, agents, environments)\n/spine             → Semantic model with business context, KPIs, knowledge, capability bindings\n/connected-tool-matrix → Which hosts/tenants/agents connected to which tools\n/tool-capability-matrix → What each tool can do and who may invoke\n```\n\n### Universal API Endpoints (already implemented)\n\n```\nGET  /api/v1/auth/session                    → Current session + tenant config\nPOST /api/v1/auth/login                      → Initiate login flow (Descope)\nGET  /api/v1/marketplace/connectors          → List all connectors\nGET  /api/v1/connectors                      → List tenant connections\nPOST /api/v1/connectors/[id]/authorization   → Authorize connection for host\nGET  /api/v1/discovery                       → Discover hosts, tools, schemas, capabilities\nGET  /api/v1/capabilities                    → List effective capabilities\nGET  /api/v1/capabilities/matrix             → Capability Matrix (hosts/roles/agents)\nGET  /api/v1/spine?type=schema               → Tenant Spine schema\nGET  /api/v1/spine?type=business-context     → Business context + KPIs\nGET  /api/v1/spine?type=capability-bindings  → MCP tools with business context mapping\nGET  /api/v1/spine?type=connectors           → Connector types with business context\nGET  /api/v1/spine?type=agents               → Agent types with business context\nGET  /api/v1/connected-tools                 → Connected Tool Matrix\nGET  /api/v1/tool-capabilities               → Tool Capability Matrix\n```\n\n---\n\n## 3. Kernel Packages (Available for Platform UI)\n\n### `@integratewise/kernel` — Unified Connector\n\n```typescript\n\nconst kernel = new KernelConnector({\n  tenant_id: \"integratewise-dev\",\n  project_id: \"platform\",\n  profile: \"development\",\n});\n\n// Access all subsystems\nkernel.getTenantSchema(); // TenantSpineSchema with business context\nkernel.getBusinessContext(); // BusinessContext\nkernel.getBusinessKPIs(); // BusinessKPIs\nkernel.getMCPConfig(); // Tenant-scoped MCP pool config\nkernel.ingestData(); // Loader → Normalizer pipeline\nkernel.executeCapability(); // Orchestrator execution\nkernel.discover(); // Discovery across all sources\nkernel.sendAgentMessage(); // Agent-to-agent communication\nkernel.getToolMemory(); // Tool memory visibility\n```\n\n### `@integratewise/loader` — Data Ingestion\n\n- Flow A: API → Loader → Normalizer → Spine\n- Flow B: Webhook → Loader → Normalizer → Spine\n- Flow C: Batch → Loader → Normalizer → Spine\n\n### `@integratewise/normalizer` — 6-Stage Pipeline\n\nNA0: Schema Detector → NA1: Canonical Transformer → NA2: SSOT Binder → NA3: Lineage Manager → NA4: Relation Binder → NA5: Spine Publisher\n\n### `@integratewise/orchestrator` — Execution Engine\n\n- Tenant-scoped capability execution\n- Governance policies\n- Concurrent execution limits\n\n### `@integratewise/contracts` — Shared Types\n\n- `TenantMCPConfig` — Tenant-scoped MCP pool (dev vs CZ)\n- `PlatformCapability` — Capability with governance\n- `BusinessContext`, `BusinessKPIs` — Tenant-defined\n\n### `@integratewise/spine-schema` — Tenant Schema\n\n- `TenantSpineSchema` — Business context, MCP tools, connectors, agents\n- `DEVELOPMENT_SPINE_SCHEMA` — Generic dev schema\n- `getTenantSpineSchema(tenantId)` — Registry lookup\n\n---\n\n## 4. Platform UI Architecture (`apps/platform`)\n\n### Current Structure (from v0 merge)\n\n```\napps/platform/\n├── app/\n│   ├── (shell)/                    # Authenticated routes\n│   │   ├── layout.tsx              # App shell wrapper\n│   │   ├── page.tsx                # Overview dashboard\n│   │   ├── my-work/page.tsx        # Tasks, approvals, inbox\n│   │   ├── communications/page.tsx # Activity feed, email\n│   │   ├── workbench/page.tsx      # Block editor + entity table\n│   │   ├── network/page.tsx        # Connector + MCP catalog\n│   │   ├── network/mcp/page.tsx    # MCP Pool page\n│   │   ├── marketplace/page.tsx    # Connector marketplace\n│   │   ├── governance/page.tsx     # Approval queue\n│   │   ├── settings/page.tsx       # Settings, roles, billing\n│   │   ├── connectors/page.tsx     # Installed integrations\n│   │   ├── agents/page.tsx         # Agent management (6 agents)\n│   │   └── approvals/page.tsx      # Approvals queue\n│   ├── .well-known/oauth-protected-resource/route.ts\n│   └── api/v1/\n│       ├── auth/session/route.ts\n│       ├── connections/route.ts\n│       ├── connections/[provider]/route.ts\n│       ├── connectors/mcp-pool/route.ts\n│       ├── keys/route.ts\n│       ├── keys/[keyId]/route.ts\n│       └── workspace/discovery/route.ts\n├── components/\n│   ├── shell/\n│   │   ├── app-shell.tsx           # Main shell\n│   │   ├── sidebar.tsx             # Navigation (needs universal routes)\n│   │   ├── topbar.tsx              # Header with auth\n│   │   └── twin-panel.tsx          # Twin Orchestrator UI\n│   ├── approvals/approval-queue.tsx\n│   ├── brand-logo.tsx\n│   ├── configuration/config-manager-panel.tsx\n│   ├── connectors/connector-catalog.tsx\n│   ├── governance/governance-queue.tsx\n│   ├── network/mcp-hub.tsx\n│   ├── network/network-catalog.tsx\n│   ├── settings/api-keys-panel.tsx\n│   ├── settings/shared-connections-panel.tsx\n│   ├── workbench/block-editor.tsx\n│   ├── workbench/entity-table.tsx\n│   └── workspace/block-editor.tsx\n└── lib/\n    ├── api-client.ts               # API client (needs universal layer integration)\n    ├── connector-manager.ts\n    ├── data.ts                     # Mock data (replace with universal APIs)\n    ├── env.ts\n    ├── hooks/use-profile-routing.ts\n    └── server/\n        ├── api-keys.ts\n        ├── session.ts\n        └── store.ts\n```\n\n---\n\n## 5. Integration Requirements for Platform UI\n\n### 5.1 One Auth Integration\n\nReplace custom auth with Universal `/auth` endpoints:\n\n- `GET /api/v1/auth/session` → Get session + tenant config\n- `POST /api/v1/auth/login` → Initiate Descope flow\n- Consent flow enforced server-side (identical for all channels)\n\n### 5.2 Platform UI Pages → Universal APIs Mapping\n\n| Platform Page      | Universal API                                                | Notes                                   |\n| ------------------ | ------------------------------------------------------------ | --------------------------------------- |\n| **Overview**       | `/api/v1/spine?type=business-context`                        | KPIs, domain, entity types              |\n| **My Work**        | `/api/v1/capabilities/matrix?dimension=roles`                | Task assignments by role                |\n| **Communications** | `/api/v1/discovery?type=hosts`                               | Host activity feed                      |\n| **Workbench**      | `/api/v1/spine?type=schema`                                  | Entity types, relationships             |\n| **Network**        | `/api/v1/marketplace/connectors` + `/api/v1/connected-tools` | Catalog + connection status             |\n| **MCP Pool**       | `/api/v1/spine?type=agents` + `/api/v1/capabilities`         | Agent types + tool capabilities         |\n| **Marketplace**    | `/api/v1/marketplace/connectors`                             | Full catalog with categories            |\n| **Governance**     | `/api/v1/capabilities/matrix?dimension=hosts`                | Approval states by host                 |\n| **Settings**       | `/api/v1/auth/session` + `/api/v1/connectors`                | Tenant config + connections             |\n| **Connectors**     | `/api/v1/connectors` + `/api/v1/tool-capabilities`           | Installed + capability matrix           |\n| **Agents**         | `/api/v1/spine?type=agents`                                  | All 6 agent types with business context |\n\n### 5.3 Shared Components (Consumed from Universal Layer)\n\nExtract these as reusable packages:\n\n```\npackages/\n├── one-auth-ui          → Login, consent, session, client management\n├── marketplace-ui       → Connector catalog, installation flow\n├── connector-ui         → Connection management, authorization, health\n├── discovery-ui         → Host discovery, tool discovery, schema discovery\n├── capability-matrix-ui → Matrix views (hosts, roles, agents, environments)\n├── spine-ui             → Schema viewer, business context, KPIs, knowledge\n├── business-context-ui  → Domain, entity types, KPI editor\n├── kpi-ui               → KPI dashboard, trends, alerts\n├── network-ui           → Connected tool matrix, tool capability matrix\n└── host-adapter-ui      → Host-specific projections\n```\n\n---\n\n## 6. Shell Separation Invariant (Critical)\n\n| Shell                            | Routes                       | Use Case                           |\n| -------------------------------- | ---------------------------- | ---------------------------------- |\n| **MarketingShell**               | `/`, `/marketplace` (public) | Unauthenticated marketing pages    |\n| **AppShell → WorkspaceShellNew** | `/app/*`                     | Authenticated business application |\n| **OnboardingShell**              | `/onboarding/*`              | First-time user onboarding         |\n| **PluginHostShell**              | `/plugin/*`                  | Embedded plugin (sandboxed iframe) |\n\n**Platform UI uses MarketingShell for public pages, AppShell for authenticated control plane.**\n\n---\n\n## 7. MCP Pool Configuration (Tenant-Scoped)\n\nFrom `@integratewise/contracts`:\n\n```typescript\n// Development tenant (us)\n{\n  tenant_id: \"integratewise-dev\",\n  profile: \"development\",\n  mcp_pool: {\n    max_connections: 50,\n    timeout_ms: 30000,\n    retry_attempts: 3,\n    health_check_interval_ms: 60000\n  }\n}\n\n// Customer Zero tenant (production)\n{\n  tenant_id: \"iw-customer-zero\",\n  profile: \"customer-zero\",\n  mcp_pool: {\n    max_connections: 200,\n    timeout_ms: 30000,\n    retry_attempts: 3,\n    health_check_interval_ms: 60000\n  }\n}\n```\n\n**MCP pool is tenant-scoped, not generic.** Platform UI must show correct pool for current tenant.\n\n---\n\n## 8. Business Context is First-Class\n\nThe Spine schema includes:\n\n```typescript\nbusiness_context: {\n  domain: \"saas\",\n  entity_types: [\"account\", \"contact\", \"deal\", \"project\", \"task\", \"ticket\"],\n  kpis: [\"revenue\", \"churn_rate\", \"nps_score\", \"ticket_resolution_time\"],\n  fields: [\n    { name: \"revenue\", type: \"number\", unit: \"USD\" },\n    { name: \"churn_rate\", type: \"number\", unit: \"percentage\" },\n    { name: \"customer_segment\", type: \"enum\", enum_values: [\"enterprise\", \"mid-market\", \"smb\", \"startup\"] },\n    // ... arbitrary fields defined by tenant\n  ]\n}\n```\n\n**Platform UI must:**\n\n- Display business context editor (domain, entity types, KPIs, fields)\n- Show KPI dashboard with real-time values\n- Map connector capabilities to business context\n- Show agent operations in business context terms\n\n---\n\n## 9. Connector Projection (Shared Across All Hosts)\n\nThe **Connector Projection** is the universal capability projection that ANY host can consume:\n\n```\nHost (ChatGPT, Claude, Platform, Web, Agent)\n    ↓ Authenticates with One Auth\n    ↓ Receives tenant + scoped grant\n    ↓ Discovery Engine identifies available sources\n    ↓ Connection Broker resolves authorized connections\n    ↓ Spine resolves business context, schema, knowledge, KPIs\n    ↓ Capability Matrix calculates effective capabilities\n    ↓ Host receives HOST-SPECIFIC capability projection\n```\n\n### Platform UI Gets Full Projection:\n\n```typescript\n// Full control-plane projection\n{\n  hostId: \"integratewise-platform\",\n  tenantId: \"integratewise-dev\",\n  capabilities: [\n    {\n      capabilityId: \"crm.deals.update\",\n      displayName: \"Update Deals\",\n      inputSchema: { deal_id: \"string\", properties: \"object\" },\n      connectionState: \"connected\",\n      accessState: \"approved\",\n      approvalState: \"approved\"\n    },\n    // ... all capabilities with full governance\n  ]\n}\n```\n\n### ChatGPT Gets Limited Projection:\n\n```typescript\n// Host-specific projection\n{\n  hostId: \"chatgpt\",\n  tenantId: \"integratewise-dev\",\n  capabilities: [\n    {\n      capabilityId: \"crm.contacts.read\",\n      displayName: \"Read Contacts\",\n      annotations: { readOnlyHint: true }\n    },\n    // ... only read capabilities, no write\n  ]\n}\n```\n\n---\n\n## 10. Implementation Checklist for Platform UI\n\n### Phase 1: One Auth Integration\n\n- [ ] Replace `lib/server/session.ts` with universal `/api/v1/auth/session` calls\n- [ ] Update `lib/api-client.ts` to use universal auth endpoints\n- [ ] Integrate Descope Inbound App flow in `components/shell/topbar.tsx`\n- [ ] Add consent UI using universal `/auth/consent` endpoint\n\n### Phase 2: Universal API Integration\n\n- [ ] Replace `lib/data.ts` mock data with real universal API calls\n- [ ] Update `components/network/mcp-hub.tsx` to use `/api/v1/spine?type=agents`\n- [ ] Update `components/connectors/connector-catalog.tsx` to use `/api/v1/marketplace/connectors`\n- [ ] Update `components/settings/shared-connections-panel.tsx` to use `/api/v1/connectors`\n- [ ] Update `components/governance/governance-queue.tsx` to use `/api/v1/capabilities/matrix`\n\n### Phase 3: Business Context & KPIs\n\n- [ ] Add business context editor in Settings (domain, entity types, KPIs, fields)\n- [ ] Add KPI dashboard in Overview using `/api/v1/spine?type=business-context`\n- [ ] Map connectors to business context in Network page\n\n### Phase 4: Agent Management (6 Agents)\n\n- [ ] Update `app/(shell)/agents/page.tsx` to show all 6 agent types\n- [ ] Show business context each agent operates on/modifies\n- [ ] Add agent configuration per tenant\n\n### Phase 5: Capability Matrices\n\n- [ ] Add Connected Tool Matrix page using `/api/v1/connected-tools`\n- [ ] Add Tool Capability Matrix page using `/api/v1/tool-capabilities`\n- [ ] Add Capability Matrix views (hosts, roles, agents) in Governance\n\n### Phase 6: Shared Component Extraction\n\n- [ ] Extract reusable UI packages from platform components\n- [ ] Publish to `@integratewise/*-ui` packages\n- [ ] Update both `apps/platform` and `apps/web` to consume shared packages\n\n---\n\n## 11. Key Files to Reference\n\n### Universal Layer (Source of Truth)\n\n```\n/Users/nirmal/Github/integratewise-live/apps/one-access/src/lib/universal-types.ts\n/Users/nirmal/Github/integratewise-live/apps/one-access/src/app/api/v1/\n/Users/nirmal/Github/integratewise-live/packages/spine-schema/src/tenant-schema.ts\n/Users/nirmal/Github/integratewise-live/packages/kernel/src/index.ts\n/Users/nirmal/Github/integratewise-live/packages/contracts/src/\n```\n\n### Platform UI (Consumer)\n\n```\n/Users/nirmal/Github/integratewise-live/apps/platform/app/(shell)/\n/Users/nirmal/Github/integratewise-live/apps/platform/components/\n/Users/nirmal/Github/integratewise-live/apps/platform/lib/\n```\n\n### Kernel Packages (Logic)\n\n```\n/Users/nirmal/Github/integratewise-live/packages/kernel/\n/Users/nirmal/Github/integratewise-live/packages/loader/\n/Users/nirmal/Github/integratewise-live/packages/normalizer/\n/Users/nirmal/Github/integratewise-live/packages/orchestrator/\n```\n\n---\n\n## 12. Verification Commands\n\n```bash\n# Typecheck\ncd /Users/nirmal/Github/integratewise-live && npx tsc --noEmit\n\n# Test kernel packages\npnpm run test --filter=@integratewise/kernel --filter=@integratewise/loader --filter=@integratewise/normalizer --filter=@integratewise/orchestrator --filter=@integratewise/contracts\n\n# Build spine-schema\npnpm run build --filter=@integratewise/spine-schema\n\n# Platform UI dev\ncd /Users/nirmal/Github/integratewise-live/apps/platform && pnpm dev\n```\n\n---\n\n**This context transfer enables the Platform UI team to build the control plane as a privileged consumer of the universal One Access Network, with all 6 agents, business context, KPIs, and host-neutral connector projections.**\n"}