Unclassified

Context Transfer: Universal Layer → Platform UI

Overview

This 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).

1. The Five Agents (Tenant Spine Schema)

Defined in packages/spine-schema/src/tenant-schema.ts:

Agent	Type	Operates On	Modifies
Twin Orchestrator	`twin-orchestrator`	context, memory, relationships, proposals, approvals	context, proposals, orchestration-plans
Schema Generator	`schema-generator`	source-schemas, tenant-context, business-knowledge	tenant-schema, field-mappings, transforms
Schema Orchestrator	`schema-orchestrator`	tenant-schema, schema-mappings, source-changes	schema-mappings, mapping-status, sync-triggers
Adaptive Auto-Tuner	`adaptive-auto-tuner`	performance-metrics, execution-patterns, kpi-trends, cost-metrics	tuning-parameters, resource-allocation, execution-strategies
Co-Worker	`co-worker`	tasks, actions, executions	tasks, actions, executions
Triage	`triage`	signals, intents, priorities	priorities, assignments

Platform UI must surface all 6 agent types in the agents management page.

2. Universal One Access Network (Host-Neutral Layer)

apps/one-access provides universal APIs consumed by ALL hosts:

Universal Routes

/auth              → Universal identity, tenant, consent, delegation, client authorization
/marketplace       → Universal catalog (connectors, MCP, plugins, agents, models, templates)
/connectors        → Universal connection & authorization management
/discovery         → Universal discovery (hosts, tools, schemas, capabilities, connections)
/capability-matrix → Effective-access view (hosts, roles, agents, environments)
/spine             → Semantic model with business context, KPIs, knowledge, capability bindings
/connected-tool-matrix → Which hosts/tenants/agents connected to which tools
/tool-capability-matrix → What each tool can do and who may invoke

Universal API Endpoints (already implemented)

GET  /api/v1/auth/session                    → Current session + tenant config
POST /api/v1/auth/login                      → Initiate login flow (Descope)
GET  /api/v1/marketplace/connectors          → List all connectors
GET  /api/v1/connectors                      → List tenant connections
POST /api/v1/connectors/[id]/authorization   → Authorize connection for host
GET  /api/v1/discovery                       → Discover hosts, tools, schemas, capabilities
GET  /api/v1/capabilities                    → List effective capabilities
GET  /api/v1/capabilities/matrix             → Capability Matrix (hosts/roles/agents)
GET  /api/v1/spine?type=schema               → Tenant Spine schema
GET  /api/v1/spine?type=business-context     → Business context + KPIs
GET  /api/v1/spine?type=capability-bindings  → MCP tools with business context mapping
GET  /api/v1/spine?type=connectors           → Connector types with business context
GET  /api/v1/spine?type=agents               → Agent types with business context
GET  /api/v1/connected-tools                 → Connected Tool Matrix
GET  /api/v1/tool-capabilities               → Tool Capability Matrix

3. Kernel Packages (Available for Platform UI)

`@integratewise/kernel` — Unified Connector


const kernel = new KernelConnector({
  tenant_id: "integratewise-dev",
  project_id: "platform",
  profile: "development",
});

// Access all subsystems
kernel.getTenantSchema(); // TenantSpineSchema with business context
kernel.getBusinessContext(); // BusinessContext
kernel.getBusinessKPIs(); // BusinessKPIs
kernel.getMCPConfig(); // Tenant-scoped MCP pool config
kernel.ingestData(); // Loader → Normalizer pipeline
kernel.executeCapability(); // Orchestrator execution
kernel.discover(); // Discovery across all sources
kernel.sendAgentMessage(); // Agent-to-agent communication
kernel.getToolMemory(); // Tool memory visibility

`@integratewise/loader` — Data Ingestion

Flow A: API → Loader → Normalizer → Spine
Flow B: Webhook → Loader → Normalizer → Spine
Flow C: Batch → Loader → Normalizer → Spine

`@integratewise/normalizer` — 6-Stage Pipeline

NA0: Schema Detector → NA1: Canonical Transformer → NA2: SSOT Binder → NA3: Lineage Manager → NA4: Relation Binder → NA5: Spine Publisher

`@integratewise/orchestrator` — Execution Engine

Tenant-scoped capability execution
Governance policies
Concurrent execution limits

`@integratewise/contracts` — Shared Types

TenantMCPConfig — Tenant-scoped MCP pool (dev vs CZ)
PlatformCapability — Capability with governance
BusinessContext, BusinessKPIs — Tenant-defined

`@integratewise/spine-schema` — Tenant Schema

TenantSpineSchema — Business context, MCP tools, connectors, agents
DEVELOPMENT_SPINE_SCHEMA — Generic dev schema
getTenantSpineSchema(tenantId) — Registry lookup

4. Platform UI Architecture (`apps/platform`)

Current Structure (from v0 merge)

apps/platform/
├── app/
│   ├── (shell)/                    # Authenticated routes
│   │   ├── layout.tsx              # App shell wrapper
│   │   ├── page.tsx                # Overview dashboard
│   │   ├── my-work/page.tsx        # Tasks, approvals, inbox
│   │   ├── communications/page.tsx # Activity feed, email
│   │   ├── workbench/page.tsx      # Block editor + entity table
│   │   ├── network/page.tsx        # Connector + MCP catalog
│   │   ├── network/mcp/page.tsx    # MCP Pool page
│   │   ├── marketplace/page.tsx    # Connector marketplace
│   │   ├── governance/page.tsx     # Approval queue
│   │   ├── settings/page.tsx       # Settings, roles, billing
│   │   ├── connectors/page.tsx     # Installed integrations
│   │   ├── agents/page.tsx         # Agent management (6 agents)
│   │   └── approvals/page.tsx      # Approvals queue
│   ├── .well-known/oauth-protected-resource/route.ts
│   └── api/v1/
│       ├── auth/session/route.ts
│       ├── connections/route.ts
│       ├── connections/[provider]/route.ts
│       ├── connectors/mcp-pool/route.ts
│       ├── keys/route.ts
│       ├── keys/[keyId]/route.ts
│       └── workspace/discovery/route.ts
├── components/
│   ├── shell/
│   │   ├── app-shell.tsx           # Main shell
│   │   ├── sidebar.tsx             # Navigation (needs universal routes)
│   │   ├── topbar.tsx              # Header with auth
│   │   └── twin-panel.tsx          # Twin Orchestrator UI
│   ├── approvals/approval-queue.tsx
│   ├── brand-logo.tsx
│   ├── configuration/config-manager-panel.tsx
│   ├── connectors/connector-catalog.tsx
│   ├── governance/governance-queue.tsx
│   ├── network/mcp-hub.tsx
│   ├── network/network-catalog.tsx
│   ├── settings/api-keys-panel.tsx
│   ├── settings/shared-connections-panel.tsx
│   ├── workbench/block-editor.tsx
│   ├── workbench/entity-table.tsx
│   └── workspace/block-editor.tsx
└── lib/
    ├── api-client.ts               # API client (needs universal layer integration)
    ├── connector-manager.ts
    ├── data.ts                     # Mock data (replace with universal APIs)
    ├── env.ts
    ├── hooks/use-profile-routing.ts
    └── server/
        ├── api-keys.ts
        ├── session.ts
        └── store.ts

5. Integration Requirements for Platform UI

5.1 One Auth Integration

Replace custom auth with Universal /auth endpoints:

GET /api/v1/auth/session → Get session + tenant config
POST /api/v1/auth/login → Initiate Descope flow
Consent flow enforced server-side (identical for all channels)

5.2 Platform UI Pages → Universal APIs Mapping

Platform Page	Universal API	Notes
Overview	`/api/v1/spine?type=business-context`	KPIs, domain, entity types
My Work	`/api/v1/capabilities/matrix?dimension=roles`	Task assignments by role
Communications	`/api/v1/discovery?type=hosts`	Host activity feed
Workbench	`/api/v1/spine?type=schema`	Entity types, relationships
Network	`/api/v1/marketplace/connectors` + `/api/v1/connected-tools`	Catalog + connection status
MCP Pool	`/api/v1/spine?type=agents` + `/api/v1/capabilities`	Agent types + tool capabilities
Marketplace	`/api/v1/marketplace/connectors`	Full catalog with categories
Governance	`/api/v1/capabilities/matrix?dimension=hosts`	Approval states by host
Settings	`/api/v1/auth/session` + `/api/v1/connectors`	Tenant config + connections
Connectors	`/api/v1/connectors` + `/api/v1/tool-capabilities`	Installed + capability matrix
Agents	`/api/v1/spine?type=agents`	All 6 agent types with business context

5.3 Shared Components (Consumed from Universal Layer)

Extract these as reusable packages:

packages/
├── one-auth-ui          → Login, consent, session, client management
├── marketplace-ui       → Connector catalog, installation flow
├── connector-ui         → Connection management, authorization, health
├── discovery-ui         → Host discovery, tool discovery, schema discovery
├── capability-matrix-ui → Matrix views (hosts, roles, agents, environments)
├── spine-ui             → Schema viewer, business context, KPIs, knowledge
├── business-context-ui  → Domain, entity types, KPI editor
├── kpi-ui               → KPI dashboard, trends, alerts
├── network-ui           → Connected tool matrix, tool capability matrix
└── host-adapter-ui      → Host-specific projections

6. Shell Separation Invariant (Critical)

Shell	Routes	Use Case
MarketingShell	`/`, `/marketplace` (public)	Unauthenticated marketing pages
AppShell → WorkspaceShellNew	`/app/*`	Authenticated business application
OnboardingShell	`/onboarding/*`	First-time user onboarding
PluginHostShell	`/plugin/*`	Embedded plugin (sandboxed iframe)

Platform UI uses MarketingShell for public pages, AppShell for authenticated control plane.

7. MCP Pool Configuration (Tenant-Scoped)

From @integratewise/contracts:

// Development tenant (us)
{
  tenant_id: "integratewise-dev",
  profile: "development",
  mcp_pool: {
    max_connections: 50,
    timeout_ms: 30000,
    retry_attempts: 3,
    health_check_interval_ms: 60000
  }
}

// Customer Zero tenant (production)
{
  tenant_id: "iw-customer-zero",
  profile: "customer-zero",
  mcp_pool: {
    max_connections: 200,
    timeout_ms: 30000,
    retry_attempts: 3,
    health_check_interval_ms: 60000
  }
}

MCP pool is tenant-scoped, not generic. Platform UI must show correct pool for current tenant.

8. Business Context is First-Class

The Spine schema includes:

business_context: {
  domain: "saas",
  entity_types: ["account", "contact", "deal", "project", "task", "ticket"],
  kpis: ["revenue", "churn_rate", "nps_score", "ticket_resolution_time"],
  fields: [
    { name: "revenue", type: "number", unit: "USD" },
    { name: "churn_rate", type: "number", unit: "percentage" },
    { name: "customer_segment", type: "enum", enum_values: ["enterprise", "mid-market", "smb", "startup"] },
    // ... arbitrary fields defined by tenant
  ]
}

Platform UI must:

Display business context editor (domain, entity types, KPIs, fields)
Show KPI dashboard with real-time values
Map connector capabilities to business context
Show agent operations in business context terms

9. Connector Projection (Shared Across All Hosts)

The Connector Projection is the universal capability projection that ANY host can consume:

Host (ChatGPT, Claude, Platform, Web, Agent)
    ↓ Authenticates with One Auth
    ↓ Receives tenant + scoped grant
    ↓ Discovery Engine identifies available sources
    ↓ Connection Broker resolves authorized connections
    ↓ Spine resolves business context, schema, knowledge, KPIs
    ↓ Capability Matrix calculates effective capabilities
    ↓ Host receives HOST-SPECIFIC capability projection

Platform UI Gets Full Projection:

// Full control-plane projection
{
  hostId: "integratewise-platform",
  tenantId: "integratewise-dev",
  capabilities: [
    {
      capabilityId: "crm.deals.update",
      displayName: "Update Deals",
      inputSchema: { deal_id: "string", properties: "object" },
      connectionState: "connected",
      accessState: "approved",
      approvalState: "approved"
    },
    // ... all capabilities with full governance
  ]
}

ChatGPT Gets Limited Projection:

// Host-specific projection
{
  hostId: "chatgpt",
  tenantId: "integratewise-dev",
  capabilities: [
    {
      capabilityId: "crm.contacts.read",
      displayName: "Read Contacts",
      annotations: { readOnlyHint: true }
    },
    // ... only read capabilities, no write
  ]
}

10. Implementation Checklist for Platform UI

Phase 1: One Auth Integration

Replace lib/server/session.ts with universal /api/v1/auth/session calls
Update lib/api-client.ts to use universal auth endpoints
Integrate Descope Inbound App flow in components/shell/topbar.tsx
Add consent UI using universal /auth/consent endpoint

Phase 2: Universal API Integration

Replace lib/data.ts mock data with real universal API calls
Update components/network/mcp-hub.tsx to use /api/v1/spine?type=agents
Update components/connectors/connector-catalog.tsx to use /api/v1/marketplace/connectors
Update components/settings/shared-connections-panel.tsx to use /api/v1/connectors
Update components/governance/governance-queue.tsx to use /api/v1/capabilities/matrix

Phase 3: Business Context & KPIs

Add business context editor in Settings (domain, entity types, KPIs, fields)
Add KPI dashboard in Overview using /api/v1/spine?type=business-context
Map connectors to business context in Network page

Phase 4: Agent Management (6 Agents)

Update app/(shell)/agents/page.tsx to show all 6 agent types
Show business context each agent operates on/modifies
Add agent configuration per tenant

Phase 5: Capability Matrices

Add Connected Tool Matrix page using /api/v1/connected-tools
Add Tool Capability Matrix page using /api/v1/tool-capabilities
Add Capability Matrix views (hosts, roles, agents) in Governance

Phase 6: Shared Component Extraction

Extract reusable UI packages from platform components
Publish to @integratewise/*-ui packages
Update both apps/platform and apps/web to consume shared packages

11. Key Files to Reference

Universal Layer (Source of Truth)

/Users/nirmal/Github/integratewise-live/apps/one-access/src/lib/universal-types.ts
/Users/nirmal/Github/integratewise-live/apps/one-access/src/app/api/v1/
/Users/nirmal/Github/integratewise-live/packages/spine-schema/src/tenant-schema.ts
/Users/nirmal/Github/integratewise-live/packages/kernel/src/index.ts
/Users/nirmal/Github/integratewise-live/packages/contracts/src/

Platform UI (Consumer)

/Users/nirmal/Github/integratewise-live/apps/platform/app/(shell)/
/Users/nirmal/Github/integratewise-live/apps/platform/components/
/Users/nirmal/Github/integratewise-live/apps/platform/lib/

Kernel Packages (Logic)

/Users/nirmal/Github/integratewise-live/packages/kernel/
/Users/nirmal/Github/integratewise-live/packages/loader/
/Users/nirmal/Github/integratewise-live/packages/normalizer/
/Users/nirmal/Github/integratewise-live/packages/orchestrator/

12. Verification Commands

# Typecheck
cd /Users/nirmal/Github/integratewise-live && npx tsc --noEmit

# Test kernel packages
pnpm run test --filter=@integratewise/kernel --filter=@integratewise/loader --filter=@integratewise/normalizer --filter=@integratewise/orchestrator --filter=@integratewise/contracts

# Build spine-schema
pnpm run build --filter=@integratewise/spine-schema

# Platform UI dev
cd /Users/nirmal/Github/integratewise-live/apps/platform && pnpm dev

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.