{"slug":"developers/FRONTEND_CREATOR_INSTRUCTIONS","title":"IntegrateWise Live — Frontend Creator Instructions","section":"developers","sectionLabel":"Developers","status":"unclassified","type":"document","path":"developers/FRONTEND_CREATOR_INSTRUCTIONS.mdx","bytes":17010,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nStatus: CURRENT\nScope: Canonical frontend execution boundary for the Live repo\nCanonical Owner: IntegrateWise Product Engineering\nLast Verified: 2026-07-12\n\n**Canonical Reference:** [docs/architecture/CANONICAL_PLATFORM_ARCHITECTURE.md](docs/architecture/CANONICAL_PLATFORM_ARCHITECTURE.md)\n\n> This document is downstream of the Canonical Platform Architecture. When this document contradicts the canonical architecture, the canonical architecture wins.\n\nThese 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.\n\nIf this document conflicts with legacy AI chat UI, L2/L3 screen shells, inferred chat paths, or inferred global drawers, this document is canonical.\n\n---\n\n## 1. Live Owns the Experience\n\nThe Live repo owns the complete user-facing experience. Frontend work must not depend on unfinished Platform implementations.\n\nBuild and complete:\n\n- Landing experience\n- Authentication UX\n- Onboarding UX\n- User Workbench surfaces:\n  - Account Success\n  - Business Operations\n  - Business Intelligence\n  - Governance and Approval Workbench\n- Twin / AI Workbench (inside L1)\n- Platform Admin UI\n- Connector Marketplace UI\n- Settings and configuration UI\n- Developer-facing UI\n\nDo not move frontend pages or product surfaces into the Platform repo.\n\n---\n\n## 2. Platform Owns Capabilities\n\nThe Platform is an external capability boundary. Frontend creators must assume the Platform provides:\n\n- Identity and authentication capabilities\n- Tenant and organization management\n- Spine and canonical entity access\n- Memory\n- Continuity\n- Integrations\n- Capabilities and actions\n- AI execution\n- Governance\n- Workflow execution\n- Communication\n- Commercial and entitlement capabilities\n- Operations and telemetry\n- Administrative capabilities\n\nThe frontend consumes these capabilities. The frontend does not implement their infrastructure.\n\n---\n\n## 3. Use Platform APIs Only\n\nAll Platform access must use the Platform client or approved API boundary.\n\nCanonical namespace:\n\n```\n/api/platform/v1/auth/*\n/api/platform/v1/tenants/*\n/api/platform/v1/spine/*\n/api/platform/v1/memory/*\n/api/platform/v1/continuity/*\n/api/platform/v1/integrations/*\n/api/platform/v1/capabilities/*\n/api/platform/v1/ai/*\n/api/platform/v1/governance/*\n/api/platform/v1/execution/*\n/api/platform/v1/communication/*\n/api/platform/v1/commercial/*\n/api/platform/v1/operations/*\n/api/platform/v1/admin/*\n```\n\nDo not create alternate API namespaces for product convenience. Do not call provider APIs directly.\n\n---\n\n## 4. Use Mock Platform Endpoints\n\nThe Live repo contains mock Platform endpoints for frontend development. Frontend creators should build against these endpoints as if they are the real Platform.\n\nMock data may be synthetic. The following must match the real Platform contract:\n\n- Route\n- HTTP method\n- Request schema\n- Response schema\n- Entity IDs\n- Status codes\n- Error format\n- Pagination\n- State transitions\n- Loading behavior\n- Permission behavior\n- Governance states\n\nDo not create arbitrary frontend-only data shapes. Mock the Platform contract, not component fixtures.\n\n---\n\n## 5. Never Import Infrastructure Providers\n\nFrontend code must not directly import or call infrastructure or AI provider SDKs.\n\nDo not directly use:\n\n- Supabase data clients\n- Cloudflare storage bindings\n- Redis or Upstash clients\n- Database clients\n- Nango APIs\n- OAuth provider SDKs for Platform integrations\n- AI provider SDKs\n- OpenAI APIs\n- Anthropic APIs\n- Gemini APIs\n- OpenRouter APIs\n- AI gateway APIs\n- Queue clients\n- Vector database clients\n\nProvider 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.\n\n---\n\n## 6. Never Bind UI to a Model or AI Provider\n\nThe frontend requests AI capabilities. The frontend does not select architectural providers.\n\nWrong:\n\n- `callClaude()`\n- `callGPT()`\n- `callGemini()`\n- `model: \"claude-sonnet\"` unless a Platform Admin surface is explicitly displaying or configuring the Platform model registry\n\nNormal product surfaces should request intent or capability.\n\nExample:\n\n```\nplatform.ai.execute({ intent: \"account-risk-analysis\", context: { entityId: accountId } })\n```\n\nTwin 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.\n\n---\n\n## 7. Spine Is Canonical Truth\n\nDo not invent separate frontend entity models when a canonical Spine entity exists. Use canonical IDs and schemas.\n\nExamples:\n\n- `usr_*`\n- `tenant_*`\n- `org_*`\n- `acc_*`\n- `contact_*`\n- `work_*`\n- `mem_*`\n- `cap_*`\n- `approval_*`\n- `execution_*`\n- `connection_*`\n\nUse the canonical Platform response. Do not flatten Platform responses merely to make components easier to build. Create selectors, view models, and presentation adapters instead.\n\nExample:\n\n```ts\nconst accountView = selectAccountWorkbenchView(accountEntity);\n```\n\nThe canonical entity remains unchanged.\n\n---\n\n## 8. UI State Is Not Platform State\n\nFrontend state may own:\n\n- Selected tab\n- Open panel\n- Modal state\n- Temporary form values\n- Filters\n- Sorting\n- Local drafts\n- Optimistic presentation state\n\nFrontend state must not become the authority for:\n\n- Tenant identity\n- Canonical entities\n- Memory\n- Approvals\n- Governance decisions\n- Integration connection state\n- Execution state\n- Entitlements\n- AI execution records\n- Audit records\n\nThose belong to Platform APIs.\n\n---\n\n## 9. Build Complete Product Flows\n\nDo not build disconnected screenshots. Every major surface should support a complete interaction flow.\n\nExample: Account Workbench\n\n```\nOpen account\n  ↓\nLoad Entity 360\n  ↓\nReview continuity context\n  ↓\nTwin surfaces intelligence\n  ↓\nUser selects proposed action\n  ↓\nGovernance evaluates action\n  ↓\nApproval requested if required\n  ↓\nAction approved\n  ↓\nExecution created\n  ↓\nExecution status displayed\n  ↓\nWorkbench refreshes\n```\n\nMock 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.\n\n---\n\n## 10. Preserve the Three Workbench Model\n\nThe product has three primary workbench categories.\n\n### User Workbench\n\nThe human operational workspace.\n\nExamples: Account Success, Business Operations, Business Intelligence\n\n### Governance and Approval Workbench\n\nThe decision and control workspace.\n\nIncludes: Approval queues, evidence, policy decisions, proposed actions, audit history\n\n### AI Workbench\n\nTwin and Hermes-facing intelligence experience.\n\nIncludes: Twin interaction, AI proposals, reasoning summaries, context awareness, capability execution visibility\n\nDo not collapse all three into a generic dashboard.\n\n---\n\n## 11. Platform Admin Is a Live Surface\n\nThe Platform Admin page exists only in the Live repo. Build the UI in Live.\n\nPlatform Admin consumes:\n\n```\n/api/platform/v1/admin/*\n```\n\nand other Platform capability APIs where required.\n\nPlatform Admin may configure and display:\n\n- Tenants\n- Users and memberships\n- Roles\n- Policies\n- Providers\n- Infrastructure configuration\n- AI providers\n- Model registry\n- AI gateways\n- Model routing\n- Connector providers\n- OAuth configuration\n- Cache configuration\n- Storage configuration\n- Queue configuration\n- Feature flags\n- Entitlements\n- Usage\n- Runtime health\n- Audit\n- Platform operations\n\nThe UI owns the experience. The Platform owns configuration authority and execution.\n\n---\n\n## 12. Provider Configuration Must Be Generic\n\nProvider configuration surfaces must be registry-driven. Do not hard-code the Platform Admin experience around one provider.\n\nWrong:\n\n```\n<SupabaseSettings />\n<OpenAISettings />\n<CloudflareSettings />\n```\n\nPreferred:\n\n```\n<ProviderConfiguration provider={provider} schema={provider.configurationSchema} />\n```\n\nThe 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.\n\n---\n\n## 13. Use the Platform Client\n\nFrontend components should not scatter raw `fetch()` calls across the application. Use the Platform client.\n\nExample:\n\n```ts\nconst account = await platform.spine.getEntity(accountId);\nconst context = await platform.continuity.getBridge({ workspaceId, entityId: accountId });\nconst result = await platform.ai.execute({ intent: \"account-risk-analysis\", entityId: accountId });\n```\n\nPreferred dependency flow:\n\n```\nPage\n  ↓\nFeature / Surface\n  ↓\nHook or Query\n  ↓\nPlatform Client\n  ↓\nPlatform API\n```\n\nAvoid:\n\n```\nComponent\n  ↓\nRandom fetch()\n  ↓\nRandom endpoint\n```\n\n---\n\n## 14. Mock and Remote Modes Must Be Interchangeable\n\nThe frontend must support:\n\n```\nPLATFORM_MODE=mock\n```\n\nand:\n\n```\nPLATFORM_MODE=remote\n```\n\nMock mode:\n\n```\nLive UI\n  ↓\nPlatform Client\n  ↓\nLive Mock Platform Endpoints\n```\n\nRemote mode:\n\n```\nLive UI\n  ↓\nPlatform Client\n  ↓\nReal Platform Gateway\n```\n\nChanging the mode must not require component rewrites. Do not add mock-specific logic inside UI components.\n\nWrong:\n\n```ts\nif (isMock) {\n  return fakeAccounts;\n}\n```\n\nCorrect:\n\n```ts\nconst accounts = await platform.spine.listEntities(...)\n```\n\nThe Platform client resolves the execution target.\n\n---\n\n## 15. Preserve Existing UI Before Rebuilding\n\nBefore creating a new page or component:\n\n- Search the Live repo\n- Identify existing surfaces\n- Identify existing components\n- Identify existing routes\n- Identify existing design patterns\n- Reuse working UI where possible\n- Connect the existing UI to Platform contracts\n\nDo not redesign working surfaces merely because the backend boundary changed. Architecture changes should not automatically trigger visual rewrites.\n\n---\n\n## 16. Do Not Consolidate Architecture in Frontend Work\n\nFrontend creators must not:\n\n- Merge Platform services\n- Move Platform services into Live\n- Reorganize provider adapters\n- Redesign Spine architecture\n- Change memory architecture\n- Replace Hermes\n- Redesign governance\n- Change canonical state ownership\n- Consolidate repositories\n- Rename Platform domains\n\nIf a Platform capability is unavailable, create or extend the corresponding mock Platform endpoint using the approved contract. Continue building the product experience.\n\n---\n\n## 17. Required States for Every Data Surface\n\nEvery Platform-backed surface must consider:\n\n- Loading\n- Success\n- Empty\n- Partial\n- Stale\n- Unauthorized\n- Forbidden\n- Not Found\n- Conflict\n- Validation Error\n- Platform Error\n- Retrying\n- Offline / Unavailable\n\nDo not assume every API call succeeds. Continuity-oriented UI should explicitly represent stale or partially hydrated context where relevant.\n\n---\n\n## 18. Governance Is a Product Experience\n\nDo not treat approval as a generic confirmation modal. A governed action may contain:\n\n- Proposal\n- Intent\n- Actor\n- Entity\n- Capability\n- Evidence\n- Policy result\n- Risk level\n- Required approval\n- Approval state\n- Execution state\n- Audit reference\n\nThe frontend should make the decision context understandable. The user must know:\n\n- What is proposed\n- Why it is proposed\n- What data supports it\n- What will happen\n- Whether approval is required\n- Who approved it\n- Whether execution succeeded\n\n---\n\n## 19. Twin Is Not a Generic Chatbot\n\nDo not build Twin as a standalone chat clone or global drawer.\n\nTwin is the AI overlay of the operational workspace. Twin should understand:\n\n- Current tenant\n- Current user\n- Current workspace\n- Current entity\n- Continuity Bridge\n- Available capabilities\n- Governance constraints\n- Recent operational context\n\nTwin can surface:\n\n- Observations\n- Risks\n- Changes\n- Summaries\n- Recommendations\n- Proposed actions\n\nActions cross the Governance and Platform execution boundaries. Twin does not directly mutate canonical state.\n\n### 19.1 Twin Placement\n\nTwin is a silent, contextual capability of the Workbench. It has no permanent\nplacement. It may surface a compact proposal card, inline explanation or\ntemporary contextual detail only when the user invokes **Ask your Twin** /\n**Assign your Twin**, or when material value passes the Silence Law.\n\nDo not introduce:\n\n- a bottom Twin panel\n- a permanent right Twin panel\n- a global AI drawer\n- a standalone chat interface\n- a separate Twin screen\n\n### 19.2 Contextual Twin Content\n\nWhen Twin surfaces contextually, the response may expose four bounded groups:\n\n1. Context — what Twin currently understands\n2. Capabilities — what connected tools can do now\n3. Proposal — a concrete, context-resolved recommendation or assignment\n4. Execution status — only after governance has issued approval and Hermes has\n   begun governed execution\n\nThis content must not become permanent navigation or compete with the active\nwork surface.\n\n### 19.3 Action Labels Are Concrete Verbs\n\nDo not expose internal action classes as UI button names.\n\nButton labels must be concrete workspace verbs.\n\nMapping examples:\n\n| Internal class | Lead UI          | Account UI          | Task UI              |\n| -------------- | ---------------- | ------------------- | -------------------- |\n| Understand     | Explain Fit      | Explain Risk        | Explain Change       |\n| Explore        | Research Account | Review History      | Inspect Dependencies |\n| Act            | Prepare Outreach | Draft Communication | Start Workflow       |\n| Govern         | Qualify Lead     | Approve Conversion  | Review Exception     |\n\nThe same internal action class must appear as a different concrete verb on each surface.\n\n### 19.4 Twin Executes In Place\n\nWhen a user clicks a Twin action, do not navigate. Update the current workspace in place.\n\nExecution steps:\n\n```\nTwin\n  ↓\nHermes\n  ↓\nCapability Fabric\n  ↓\nConnected Tool / Provider\n  ↓\nEvidence\n  ↓\nSpine Context\n  ↓\nTwin\n  ↓\nWorkspace State Mutation\n```\n\nAfter execution:\n\n- The current page updates with new state\n- Activity records the execution\n- Evidence is attached\n- Twin actions re-resolve immediately\n\n### 19.5 Twin Action Re-resolution\n\nAfter every Twin execution, the set of recommended actions must update to reflect the new workspace state.\n\nBefore research:\n\n- Explain Fit\n- Research Account\n- Prepare Outreach\n- Qualify Lead\n\nAfter research:\n\n- Explain Buying Signals\n- Compare ICP\n- Draft CIO Outreach\n- Qualify Lead\n\nRe-resolution is mandatory. Stale action sets are a bug.\n\n### 19.6 Collapsed Twin on List Surfaces\n\nOn list surfaces, do not permanently consume the full right panel width.\n\nUse a collapsed Twin action rail on the right edge.\n\nWhen the user interacts with a row or opens Twin, the right panel expands and resolves context for that selection.\n\nList surface context rules:\n\n- No selection: Twin context = collection\n- Row selected: Twin context = selected entity\n- Panel closed: rail remains visible\n\n### 19.7 Twin Context Is Surface-Aware\n\nTwin context is derived from the active surface and selected entity:\n\n- Leads page: Lead collection\n- Lead detail: Lead\n- Account page: Account\n- Task page: Task\n- Workbench: Current operational state\n\nTwin must not assume a fixed entity type. The context resolver is surface-driven.\n\n---\n\n## 20. Frontend Completion Rule\n\nA frontend surface is complete when:\n\n- Route works\n- Navigation works\n- Platform client is used\n- Mock endpoint exists\n- Contract is respected\n- Loading state exists\n- Empty state exists\n- Error state exists\n- Primary interactions work\n- Governance is respected\n- Responsive behavior works\n- No direct provider dependency exists\n- Mock and remote modes are interchangeable\n- Twin is contextual, in-place, and re-resolves after execution\n\nVisual completion alone is not product completion.\n\n---\n\n## 21. Final Architecture Rule\n\nProduct owns experience. Platform owns capability and authority. Providers are configurable execution substrates.\n\nLive 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.\n\n---\n\n## 22. Twin Surface Doctrine (Canonical)\n\n> Twin occupies the contextual right intelligence surface already present in the IntegrateWise UI.\n>\n> 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.\n>\n> Tools are execution providers. Capabilities explain what is available. Actions are concrete user verbs. Results mutate the workspace in realtime.\n"}