Unclassified

IntegrateWise Live — Frontend Creator Instructions

Status: CURRENT
Scope: Canonical frontend execution boundary for the Live repo
Canonical Owner: IntegrateWise Product Engineering
Last Verified: 2026-07-12

Canonical Reference: docs/architecture/CANONICAL_PLATFORM_ARCHITECTURE.md

This document is downstream of the Canonical Platform Architecture. When this document contradicts the canonical architecture, the canonical architecture wins.

These instructions override any earlier frontend guidance in this repo that describes Twin as a chat interface, a bottom drawer, a standalone surface, or a generic AI overlay.

If this document conflicts with legacy AI chat UI, L2/L3 screen shells, inferred chat paths, or inferred global drawers, this document is canonical.

1. Live Owns the Experience

The Live repo owns the complete user-facing experience. Frontend work must not depend on unfinished Platform implementations.

Build and complete:

Landing experience
Authentication UX
Onboarding UX
User Workbench surfaces:
- Account Success
- Business Operations
- Business Intelligence
- Governance and Approval Workbench
Twin / AI Workbench (inside L1)
Platform Admin UI
Connector Marketplace UI
Settings and configuration UI
Developer-facing UI

Do not move frontend pages or product surfaces into the Platform repo.

2. Platform Owns Capabilities

The Platform is an external capability boundary. Frontend creators must assume the Platform provides:

Identity and authentication capabilities
Tenant and organization management
Spine and canonical entity access
Memory
Continuity
Integrations
Capabilities and actions
AI execution
Governance
Workflow execution
Communication
Commercial and entitlement capabilities
Operations and telemetry
Administrative capabilities

The frontend consumes these capabilities. The frontend does not implement their infrastructure.

3. Use Platform APIs Only

All Platform access must use the Platform client or approved API boundary.

Canonical namespace:

/api/platform/v1/auth/*
/api/platform/v1/tenants/*
/api/platform/v1/spine/*
/api/platform/v1/memory/*
/api/platform/v1/continuity/*
/api/platform/v1/integrations/*
/api/platform/v1/capabilities/*
/api/platform/v1/ai/*
/api/platform/v1/governance/*
/api/platform/v1/execution/*
/api/platform/v1/communication/*
/api/platform/v1/commercial/*
/api/platform/v1/operations/*
/api/platform/v1/admin/*

Do not create alternate API namespaces for product convenience. Do not call provider APIs directly.

4. Use Mock Platform Endpoints

The Live repo contains mock Platform endpoints for frontend development. Frontend creators should build against these endpoints as if they are the real Platform.

Mock data may be synthetic. The following must match the real Platform contract:

Route
HTTP method
Request schema
Response schema
Entity IDs
Status codes
Error format
Pagination
State transitions
Loading behavior
Permission behavior
Governance states

Do not create arbitrary frontend-only data shapes. Mock the Platform contract, not component fixtures.

5. Never Import Infrastructure Providers

Frontend code must not directly import or call infrastructure or AI provider SDKs.

Do not directly use:

Supabase data clients
Cloudflare storage bindings
Redis or Upstash clients
Database clients
Nango APIs
OAuth provider SDKs for Platform integrations
AI provider SDKs
OpenAI APIs
Anthropic APIs
Gemini APIs
OpenRouter APIs
AI gateway APIs
Queue clients
Vector database clients

Provider execution belongs behind the Platform boundary. Authentication UI may render the configured authentication experience, but application authorization and Platform identity context must come through the Platform contract.

6. Never Bind UI to a Model or AI Provider

The frontend requests AI capabilities. The frontend does not select architectural providers.

Wrong:

callClaude()
callGPT()
callGemini()
model: "claude-sonnet" unless a Platform Admin surface is explicitly displaying or configuring the Platform model registry

Normal product surfaces should request intent or capability.

Example:

platform.ai.execute({ intent: "account-risk-analysis", context: { entityId: accountId } })

Twin requests intelligence. Hermes orchestrates execution. Governance determines permission. The Platform router selects the model. The AI gateway determines transport. The configured provider performs inference. The frontend renders the result.

7. Spine Is Canonical Truth

Do not invent separate frontend entity models when a canonical Spine entity exists. Use canonical IDs and schemas.

Examples:

usr_*
tenant_*
org_*
acc_*
contact_*
work_*
mem_*
cap_*
approval_*
execution_*
connection_*

Use the canonical Platform response. Do not flatten Platform responses merely to make components easier to build. Create selectors, view models, and presentation adapters instead.

Example:

const accountView = selectAccountWorkbenchView(accountEntity);

The canonical entity remains unchanged.

8. UI State Is Not Platform State

Frontend state may own:

Selected tab
Open panel
Modal state
Temporary form values
Filters
Sorting
Local drafts
Optimistic presentation state

Frontend state must not become the authority for:

Tenant identity
Canonical entities
Memory
Approvals
Governance decisions
Integration connection state
Execution state
Entitlements
AI execution records
Audit records

Those belong to Platform APIs.

9. Build Complete Product Flows

Do not build disconnected screenshots. Every major surface should support a complete interaction flow.

Example: Account Workbench

Open account
  ↓
Load Entity 360
  ↓
Review continuity context
  ↓
Twin surfaces intelligence
  ↓
User selects proposed action
  ↓
Governance evaluates action
  ↓
Approval requested if required
  ↓
Action approved
  ↓
Execution created
  ↓
Execution status displayed
  ↓
Workbench refreshes

Mock endpoints should support this flow. Buttons must perform actions. Forms must submit. Filters must work. Drawers must open. Navigation must work. Loading states must exist. Empty states must exist. Error states must exist. Permission states must exist.

10. Preserve the Three Workbench Model

The product has three primary workbench categories.

User Workbench

The human operational workspace.

Examples: Account Success, Business Operations, Business Intelligence

Governance and Approval Workbench

The decision and control workspace.

Includes: Approval queues, evidence, policy decisions, proposed actions, audit history

AI Workbench

Twin and Hermes-facing intelligence experience.

Includes: Twin interaction, AI proposals, reasoning summaries, context awareness, capability execution visibility

Do not collapse all three into a generic dashboard.

11. Platform Admin Is a Live Surface

The Platform Admin page exists only in the Live repo. Build the UI in Live.

Platform Admin consumes:

/api/platform/v1/admin/*

and other Platform capability APIs where required.

Platform Admin may configure and display:

Tenants
Users and memberships
Roles
Policies
Providers
Infrastructure configuration
AI providers
Model registry
AI gateways
Model routing
Connector providers
OAuth configuration
Cache configuration
Storage configuration
Queue configuration
Feature flags
Entitlements
Usage
Runtime health
Audit
Platform operations

The UI owns the experience. The Platform owns configuration authority and execution.

12. Provider Configuration Must Be Generic

Provider configuration surfaces must be registry-driven. Do not hard-code the Platform Admin experience around one provider.

Wrong:

<SupabaseSettings />
<OpenAISettings />
<CloudflareSettings />

Preferred:

<ProviderConfiguration provider={provider} schema={provider.configurationSchema} />

The Platform should return provider metadata and configuration schemas. The frontend renders the appropriate configuration experience. Provider-specific branding or helper content may exist as presentation metadata. Provider-specific architecture must not be embedded in the page.

13. Use the Platform Client

Frontend components should not scatter raw fetch() calls across the application. Use the Platform client.

Example:

const account = await platform.spine.getEntity(accountId);
const context = await platform.continuity.getBridge({ workspaceId, entityId: accountId });
const result = await platform.ai.execute({ intent: "account-risk-analysis", entityId: accountId });

Preferred dependency flow:

Page
  ↓
Feature / Surface
  ↓
Hook or Query
  ↓
Platform Client
  ↓
Platform API

Avoid:

Component
  ↓
Random fetch()
  ↓
Random endpoint

14. Mock and Remote Modes Must Be Interchangeable

The frontend must support:

PLATFORM_MODE=mock

and:

PLATFORM_MODE=remote

Mock mode:

Live UI
  ↓
Platform Client
  ↓
Live Mock Platform Endpoints

Remote mode:

Live UI
  ↓
Platform Client
  ↓
Real Platform Gateway

Changing the mode must not require component rewrites. Do not add mock-specific logic inside UI components.

Wrong:

if (isMock) {
  return fakeAccounts;
}

Correct:

const accounts = await platform.spine.listEntities(...)

The Platform client resolves the execution target.

15. Preserve Existing UI Before Rebuilding

Before creating a new page or component:

Search the Live repo
Identify existing surfaces
Identify existing components
Identify existing routes
Identify existing design patterns
Reuse working UI where possible
Connect the existing UI to Platform contracts

Do not redesign working surfaces merely because the backend boundary changed. Architecture changes should not automatically trigger visual rewrites.

16. Do Not Consolidate Architecture in Frontend Work

Frontend creators must not:

Merge Platform services
Move Platform services into Live
Reorganize provider adapters
Redesign Spine architecture
Change memory architecture
Replace Hermes
Redesign governance
Change canonical state ownership
Consolidate repositories
Rename Platform domains

If a Platform capability is unavailable, create or extend the corresponding mock Platform endpoint using the approved contract. Continue building the product experience.

17. Required States for Every Data Surface

Every Platform-backed surface must consider:

Loading
Success
Empty
Partial
Stale
Unauthorized
Forbidden
Not Found
Conflict
Validation Error
Platform Error
Retrying
Offline / Unavailable

Do not assume every API call succeeds. Continuity-oriented UI should explicitly represent stale or partially hydrated context where relevant.

18. Governance Is a Product Experience

Do not treat approval as a generic confirmation modal. A governed action may contain:

Proposal
Intent
Actor
Entity
Capability
Evidence
Policy result
Risk level
Required approval
Approval state
Execution state
Audit reference

The frontend should make the decision context understandable. The user must know:

What is proposed
Why it is proposed
What data supports it
What will happen
Whether approval is required
Who approved it
Whether execution succeeded

19. Twin Is Not a Generic Chatbot

Do not build Twin as a standalone chat clone or global drawer.

Twin is the AI overlay of the operational workspace. Twin should understand:

Current tenant
Current user
Current workspace
Current entity
Continuity Bridge
Available capabilities
Governance constraints
Recent operational context

Twin can surface:

Observations
Risks
Changes
Summaries
Recommendations
Proposed actions

Actions cross the Governance and Platform execution boundaries. Twin does not directly mutate canonical state.

19.1 Twin Placement

Twin is a silent, contextual capability of the Workbench. It has no permanent
placement. It may surface a compact proposal card, inline explanation or
temporary contextual detail only when the user invokes Ask your Twin /
Assign your Twin, or when material value passes the Silence Law.

Do not introduce:

a bottom Twin panel
a permanent right Twin panel
a global AI drawer
a standalone chat interface
a separate Twin screen

19.2 Contextual Twin Content

When Twin surfaces contextually, the response may expose four bounded groups:

Context — what Twin currently understands
Capabilities — what connected tools can do now
Proposal — a concrete, context-resolved recommendation or assignment
Execution status — only after governance has issued approval and Hermes has
begun governed execution

This content must not become permanent navigation or compete with the active
work surface.

19.3 Action Labels Are Concrete Verbs

Do not expose internal action classes as UI button names.

Button labels must be concrete workspace verbs.

Mapping examples:

Internal class	Lead UI	Account UI	Task UI
Understand	Explain Fit	Explain Risk	Explain Change
Explore	Research Account	Review History	Inspect Dependencies
Act	Prepare Outreach	Draft Communication	Start Workflow
Govern	Qualify Lead	Approve Conversion	Review Exception

The same internal action class must appear as a different concrete verb on each surface.

19.4 Twin Executes In Place

When a user clicks a Twin action, do not navigate. Update the current workspace in place.

Execution steps:

Twin
  ↓
Hermes
  ↓
Capability Fabric
  ↓
Connected Tool / Provider
  ↓
Evidence
  ↓
Spine Context
  ↓
Twin
  ↓
Workspace State Mutation

After execution:

The current page updates with new state
Activity records the execution
Evidence is attached
Twin actions re-resolve immediately

19.5 Twin Action Re-resolution

After every Twin execution, the set of recommended actions must update to reflect the new workspace state.

Before research:

Explain Fit
Research Account
Prepare Outreach
Qualify Lead

After research:

Explain Buying Signals
Compare ICP
Draft CIO Outreach
Qualify Lead

Re-resolution is mandatory. Stale action sets are a bug.

19.6 Collapsed Twin on List Surfaces

On list surfaces, do not permanently consume the full right panel width.

Use a collapsed Twin action rail on the right edge.

When the user interacts with a row or opens Twin, the right panel expands and resolves context for that selection.

List surface context rules:

No selection: Twin context = collection
Row selected: Twin context = selected entity
Panel closed: rail remains visible

19.7 Twin Context Is Surface-Aware

Twin context is derived from the active surface and selected entity:

Leads page: Lead collection
Lead detail: Lead
Account page: Account
Task page: Task
Workbench: Current operational state

Twin must not assume a fixed entity type. The context resolver is surface-driven.

20. Frontend Completion Rule

A frontend surface is complete when:

Route works
Navigation works
Platform client is used
Mock endpoint exists
Contract is respected
Loading state exists
Empty state exists
Error state exists
Primary interactions work
Governance is respected
Responsive behavior works
No direct provider dependency exists
Mock and remote modes are interchangeable
Twin is contextual, in-place, and re-resolves after execution

Visual completion alone is not product completion.

21. Final Architecture Rule

Product owns experience. Platform owns capability and authority. Providers are configurable execution substrates.

Live builds against Platform contracts. Mock endpoints allow Live to move independently. The same frontend must work when mock Platform execution is replaced by the real Platform runtime.

22. Twin Surface Doctrine (Canonical)

Twin occupies the contextual right intelligence surface already present in the IntegrateWise UI.

Twin observes the active workspace, resolves available capabilities from connected tools, proposes four context-relevant actions, executes approved capability plans in realtime, and returns every work product or state change to the workspace where the work belongs.

Tools are execution providers. Capabilities explain what is available. Actions are concrete user verbs. Results mutate the workspace in realtime.