{"slug":"architecture/BROWSER_FRONTEND_AND_MCP_PRODUCT_CODE_BRIEF","title":"Browser Frontend and MCP Product Code Brief","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/BROWSER_FRONTEND_AND_MCP_PRODUCT_CODE_BRIEF.mdx","bytes":19863,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Implementation briefing  \n**Date:** 2026-07-29  \n**Audience:** Frontend, Platform, MCP, Customer Zero and release engineers  \n**Governing specifications:**\n`CUSTOMER_ZERO_TO_EXTERNAL_PRODUCT_AND_MARKETPLACE_SPEC.md`,\n`FRONTEND_PLATFORM_API_AND_DISCOVERY_SPEC.md` and\n`IW_SPINE_NETWORK_PLUGIN_AND_MCP_MARKETPLACE_CONTRACT.md`\n\n## 1. Product to build\n\nThe frontend repository owns the complete IntegrateWise browser Product:\n\n- onboarding;\n- full Workbench;\n- tables, records, pages and canvases;\n- Home, My Work, Communications, Personal and Work projections;\n- permitted Platform and Administration modules;\n- contextual Silent Twin;\n- Connector Marketplace and activation;\n- approvals and execution status;\n- organizational and operational-memory projections.\n\nIt is implemented for Customer Zero first and then promoted as the external\nbrowser Product from the same versioned codebase.\n\n```text\nIW-Spine-Network Plugin\n→ focused UI inside ChatGPT/Claude/compatible host\n→ optional Open Workbench\n\nIW-Spine-Network MCP\n→ remote 19-tool protocol endpoint\n→ text/JSON or focused widget in MCP client\n→ Open Workbench\n→ complete browser Product from the frontend repository\n```\n\nThe Plugin and browser are two presentations of the same work, context, Spine\nand governed capabilities. They are not separate products or sources of truth.\n\n## 2. Browser Product versus Plugin Product\n\n| Concern             | Plugin/hosted application                                              | Browser frontend                                                                     |\n| ------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |\n| Primary location    | Inside ChatGPT, Claude or compatible host                              | Standalone browser                                                                   |\n| Controller          | AI host owns conversation/model                                        | IntegrateWise owns browser experience; Platform model policy owns IW reasoning       |\n| Experience          | Focused current work, context, search, proposal, approval and progress | Complete Workbench, tables, pages, canvases, connectors, Platform and Administration |\n| Transport           | Host MCP App bridge                                                    | One typed Gateway client                                                             |\n| Full Workbench      | Launch target only                                                     | Primary surface                                                                      |\n| Host-connected apps | Host composition or explicit delegation                                | Shows persisted delegated bindings and IW direct connections                         |\n| Product state       | Bounded hosted operational state                                       | Bounded browser/server operational state                                             |\n| Canonical truth     | Platform only                                                          | Platform only                                                                        |\n| Internal MCP Pool   | Never published                                                        | Customer Zero operator module only; never ordinary customer access                   |\n\nThe Plugin must not attempt to reproduce the entire browser Workbench. The\nbrowser frontend must not depend on an AI host to function.\n\n## 3. MCP marketplace relationship\n\n`IW-Spine-Network MCP` is the protocol package. The frontend repository supplies\nthe complete browser destination associated with that package.\n\n```text\nUser finds IW-Spine-Network MCP\n→ connects remote MCP\n→ completes OAuth and consent\n→ Gateway resolves/creates logical tenant, workspace and membership\n→ client receives exact 19-tool catalog\n→ client can use text/JSON or focused MCP widgets\n→ Open Workbench creates a secure handoff\n→ browser frontend resumes the permitted tenant/work context\n```\n\nThe MCP server remains Platform-owned. The frontend repository does not host an\nindependent copy of the public tool server unless the deployment manifest\nexplicitly identifies a thin proxy that preserves the same Platform contract.\n\n## 4. No deployment during onboarding\n\nThe browser application and Platform services are already deployed.\n\nBrowser signup or MCP Workbench launch performs logical provisioning only:\n\n```text\nauthenticate\n→ resolve/create tenant_account_id\n→ resolve/create tenant_id\n→ resolve/create workspace and membership\n→ allocate stable spine_network_id\n→ apply activation-profile definitions\n→ initialize bounded operational/frontend state\n→ return workspace Discovery\n→ compose and render Workbench\n```\n\nIt does not deploy:\n\n- a new frontend;\n- a new Worker;\n- a new database;\n- a new queue or bucket;\n- a new MCP server;\n- a copy of Customer Zero.\n\nAll initial external users run inside the IntegrateWise-managed shared SaaS\nenvironment with separate logical tenant boundaries.\n\n## 5. Customer Zero and external profiles\n\nThe frontend codebase produces one browser artifact with two\nserver-authoritative profiles:\n\n| Concern             | Customer Zero browser                         | External browser                                            |\n| ------------------- | --------------------------------------------- | ----------------------------------------------------------- |\n| Profile             | `cz-mcp-workbench`                            | `external-mcp-workbench`                                    |\n| Tenant              | `iw-customer-zero` after membership proof     | Dynamically resolved logical tenant                         |\n| Entry               | Direct browser, private MCP or Plugin handoff | Direct browser, public MCP or Plugin handoff                |\n| Data                | IntegrateWise operations                      | Tenant-isolated customer data                               |\n| Connections         | IntegrateWise-owned                           | Customer-consented                                          |\n| Internal operations | RBAC-gated                                    | Not exposed                                                 |\n| Public tools        | Exact 19                                      | Exact 19                                                    |\n| Navigation          | Customer Zero RBAC projections                | Customer RBAC × role × department × industry × availability |\n| Approval            | Mandatory                                     | Mandatory                                                   |\n\nDo not build separate Customer Zero and external frontends. Do not maintain\nlong-lived profile branches.\n\n## 6. Frontend repository ownership\n\n### 6.1 Browser application\n\nThe repository owns:\n\n- authentication and marketplace-origin presentation;\n- onboarding and activation progress;\n- discovery-driven navigation;\n- projection rendering;\n- entity tables and records;\n- document/page rendering;\n- editable Workbench canvases;\n- drafts and optimistic presentation;\n- contextual Twin interactions;\n- Four Buttons;\n- Connector Marketplace;\n- approval and execution receipts;\n- responsive and accessible behavior;\n- browser error, partial, stale and degraded states.\n\n### 6.2 Server-side Product runtime\n\nWhere the frontend repository includes route handlers or a backend-for-frontend,\nthat server-side Product runtime may own bounded, tenant-scoped state:\n\n- browser session handoff records;\n- short-lived projection caches;\n- layout and user-preference state;\n- draft and autosave state;\n- event outbox/inbox;\n- idempotency records;\n- pending upload metadata;\n- agent scratchpad and working-memory drafts;\n- operational-memory candidates;\n- notification/read cursors;\n- resumable UI workflow state.\n\nThis state is non-authoritative, bounded and reconstructable. Sensitive durable\nstate must remain server-side; it must not be placed in browser local storage.\n\n### 6.3 Browser client\n\nThe browser itself may hold:\n\n- selected route/entity/view;\n- unsaved form state;\n- temporary canvas edits;\n- bounded query cache;\n- accessibility and display preferences;\n- short-lived handoff/session references.\n\nTenant switches, sign-out and permission reductions must clear affected\ncaches immediately.\n\n## 7. What remains Platform-owned\n\nThe frontend does not own:\n\n- identity or tenant authority;\n- provider credentials;\n- connector runtimes;\n- deterministic normalization;\n- Operational Spine authority;\n- Triage promotion policy;\n- Canonical Spine/Fortress;\n- canonical memory;\n- Projection contract authority;\n- Twin model routing;\n- Capability registry/resolver;\n- Governance or approval tokens;\n- Hermes;\n- provider execution;\n- internal MCP Pool;\n- public MCP server authority.\n\nThe frontend consumes semantic contracts; it does not know the internal service\ntopology.\n\n## 8. Required repository shape\n\n```text\napps/\n  workbench/                    # complete browser Product\n  product-runtime/              # optional BFF/route handlers\npackages/\n  ui/                           # shared components and design tokens\n  platform-client/              # one generated Gateway client\n  projection-renderer/          # entity/page/table/canvas projections\n  workbench-state/              # bounded drafts/preferences\n  operational-state/            # server-side Product operational store\n  agent-working-memory/         # scratchpad/candidate contracts\n  marketplace-handoff/          # Plugin/MCP browser handoff\nprofiles/\n  customer-zero/\n  external/\ntests/\n  contract/\n  discovery/\n  rbac/\n  tenant-isolation/\n  handoff/\n  operational-memory/\n  approval/\n  browser-e2e/\n```\n\nNo profile directory contains credentials or fixed tenant authority.\n\n## 9. Secure Plugin/MCP-to-browser handoff\n\nThe Plugin or MCP client must not place access tokens, credentials, tenant IDs,\nraw context or provider data in a browser URL.\n\n### 9.1 Handoff creation\n\n```text\nPlugin/MCP client requests Open Workbench\n→ Platform verifies OAuth identity and tenant membership\n→ Platform creates short-lived one-time handoff\n→ handoff stores tenant, workspace, installation, context_ref and return policy\n→ client receives opaque handoff_id + approved Workbench URL\n```\n\n### 9.2 Browser exchange\n\n```text\nbrowser opens /handoff/{opaque_id}\n→ browser authenticates with Clerk if required\n→ frontend server exchanges one-time handoff with Gateway\n→ Gateway verifies user, tenant, workspace, expiry and consumption state\n→ handoff is consumed\n→ browser receives normal session-bound Discovery\n→ Workbench opens the permitted projection/context\n```\n\nHandoff requirements:\n\n- opaque and unguessable identifier;\n- short expiry;\n- one-time consumption;\n- server-side storage;\n- installation and user binding;\n- intended tenant/workspace binding;\n- replay rejection;\n- audit event;\n- no bearer token in query parameters;\n- no raw context or secrets in URL;\n- safe fallback to normal login if expired.\n\n## 10. Direct browser entry\n\nThe browser is also a normal daily-use Product and does not require MCP or\nPlugin entry.\n\n```text\nuser opens IntegrateWise\n→ Clerk sign-in\n→ Gateway resolves tenant/workspace/membership\n→ GET /api/v1/workspace/discovery\n→ render permitted Workbench\n```\n\nMarketplace origin is preserved only as onboarding/resume context. It does not\nchange tenant authority or create a separate Product.\n\n## 11. Discovery is the first read\n\nAfter authentication, workspace switch or handoff exchange:\n\n```text\nGET /api/v1/workspace/discovery\n→ identity + tenant + membership\n→ RBAC and entitlements\n→ activation profile\n→ navigation and projections\n→ connector and capability state\n→ marketplace installation state\n→ partial/degraded blockers\n```\n\nThe frontend does not render authoritative navigation from hard-coded provider\nlists or department schemas.\n\nEvery visible module must map to:\n\n- `projectionId`;\n- contract version;\n- permitted read mode;\n- permitted commands;\n- capability requirements;\n- approval requirements;\n- loading/partial/degraded/forbidden behavior.\n\n## 12. One frontend-to-Platform client\n\n```text\nNEXT_PUBLIC_IW_API_URL\n→ typed Gateway client\n→ Clerk token forwarding\n→ correlation and idempotency\n→ response validation\n→ normalized error states\n```\n\nComponents do not construct service URLs.\n\nThe browser never calls:\n\n- Neon;\n- D1, KV or R2 directly;\n- Nango or credential storage;\n- provider APIs;\n- Hermes;\n- internal Workers;\n- internal MCP Pool.\n\n## 13. Workbench and projection behavior\n\nThe Workbench is one surface. Role, department and industry select RBAC\nprojections over tenant-level entities; they do not create department schemas.\n\nThe frontend renders:\n\n- entity tables;\n- record detail and timelines;\n- related entities and evidence;\n- documents and knowledge;\n- tasks, queues, approvals and notifications;\n- pages and database-style views;\n- editable canvases;\n- lifecycle and activity projections;\n- organizational-memory projections.\n\nCRUD behavior:\n\n```text\nuser edits projection/draft\n→ frontend validates local shape\n→ semantic command sent to Gateway\n→ Platform returns accepted/pending/rejected state\n→ UI displays receipt\n→ canonical outcome appears only after governed lifecycle\n```\n\nThe browser never reports canonical success before the Platform returns the\ncorresponding accepted/promoted outcome.\n\n## 14. Twin, agents and models\n\nIn the browser, IntegrateWise—not an external host—owns the Product interaction\nloop.\n\n- Twin is a capability of the Workbench, silent by default.\n- Material clicks assemble or reuse Active Context.\n- Twin participates at THINK when explicitly asked or when a material signal\n  qualifies.\n- `Ask your Twin` explains or prepares.\n- `Assign your Twin` creates a governed assignment/proposal.\n- `Approve Twin's Action` is the explicit human authority boundary.\n\nThe browser frontend does not select model vendors. Configuration/model policy\nresolves models, fallbacks, privacy, rate limits and budgets.\n\nAgent working-memory state may be staged in the Product operational runtime.\nPromoted user or organizational memory remains Platform-owned.\n\n## 15. Operational and agent memory\n\n| State                        | Frontend/Product runtime                | Platform                                |\n| ---------------------------- | --------------------------------------- | --------------------------------------- |\n| Unsaved draft                | Owns temporarily                        | Not yet received                        |\n| Canvas/layout preference     | Owns bounded state                      | Optional governed profile sync          |\n| Agent scratchpad             | Owns bounded working state              | Not canonical                           |\n| Active Context cache         | Owns tenant/RBAC-keyed projection cache | Supplies authoritative context contract |\n| Operational-memory candidate | Stages and submits                      | Triage classifies and queues            |\n| Canonical memory             | Displays projection only                | Owns through governed promotion         |\n| Canonical entity truth       | Displays/edits semantic projection      | Owns through governed writers           |\n\nSynchronization is command/event based:\n\n```text\nfrontend draft or agent outcome\n→ Product outbox\n→ Gateway semantic event/command\n→ Pipeline + Triage\n→ Operational Spine\n→ promotion queue\n→ human/policy decision\n→ Governed Spine Writer\n→ Canonical Spine\n→ projection invalidation\n→ frontend refresh\n```\n\nThere is no frontend-database-to-Fortress replication path.\n\n## 16. Connector and application behavior\n\nThe browser shows a unified connection/network projection with explicit origin:\n\n- `iw_direct`;\n- `host_delegated`;\n- `host_composed`.\n\n`iw_direct` connections are persistent IntegrateWise connections.\n\n`host_delegated` connections are persistent only when the host, user/admin and\nIW all support and authorize the delegation contract.\n\n`host_composed` is a host/session capability. The browser may show its last\nknown availability when linked to the same installation, but it must not claim\ndirect credentials or persistent synchronization.\n\nWhen data is missing, the browser presents Connector Marketplace rather than\nsilently selecting a provider.\n\n## 17. Browser states\n\nEvery major surface supports:\n\n- loading;\n- empty;\n- ready;\n- stale;\n- partial;\n- degraded;\n- unauthorized;\n- forbidden;\n- conflict;\n- pending approval;\n- execution in progress;\n- reconciled;\n- revoked.\n\nLive failure never falls back silently to demo or seed data.\n\n## 18. Customer Zero implementation sequence\n\n1. Build the browser shell and one typed Gateway client.\n2. Implement real Clerk/Gateway identity and logical tenant allocation.\n3. Make Discovery the first read.\n4. Implement Customer Zero RBAC projections.\n5. Implement bounded frontend/Product operational state.\n6. Implement entity tables, records, pages and canvases.\n7. Implement Active Context, Twin and Four Buttons.\n8. Implement Connector Marketplace and activation status.\n9. Implement approval, execution receipt and reconciliation.\n10. Implement MCP and Plugin one-time Workbench handoff.\n11. Run Customer Zero daily work through the browser.\n12. Activate the same artifact for a clean external logical tenant.\n\n## 19. MCP and browser release gates\n\nBefore MCP marketplace publication:\n\n- MCP protected-resource and OAuth metadata are correct;\n- exact 19-tool catalog is verified;\n- ordinary-client text/JSON fallback is meaningful;\n- `Open Workbench` creates a secure one-time handoff;\n- expired/replayed/cross-tenant handoffs fail;\n- browser Discovery resolves the same tenant and permissions;\n- Customer Zero and external profiles use the same build;\n- no Product code calls Platform internals directly;\n- operational-memory promotion is governed;\n- browser works without ChatGPT or another AI host.\n\n## 20. Later dedicated-partition movement\n\nThe browser URL and Product artifact remain stable if a logical tenant later\nmoves from shared infrastructure to a dedicated partition.\n\nGateway resolves the tenant and routes requests to the approved partition. The\nbrowser does not know the database, Worker, queue, bucket or model location.\n\n## 21. Stop-ship conditions\n\nDo not release if:\n\n- browser onboarding deploys infrastructure;\n- external users are placed inside `iw-customer-zero`;\n- tenant, role or permission authority is accepted from browser state;\n- MCP or Plugin puts bearer tokens or tenant IDs in Workbench URLs;\n- frontend directly calls a database, provider, Hermes or internal MCP;\n- navigation or schema is partitioned by department;\n- the browser requires an AI host to operate;\n- agent working memory writes canonical truth directly;\n- Product operational state becomes an unbounded competing Spine;\n- UI reports provider/canonical success before reconciliation;\n- internal MCP Pool is visible to ordinary external users.\n\n## 22. Definition of done\n\nThe frontend code briefing is satisfied when:\n\n1. one browser artifact serves Customer Zero and external profiles;\n2. direct browser, Plugin handoff and MCP handoff resolve the same logical\n   tenant and Workbench;\n3. the complete Workbench functions independently of an AI host;\n4. MCP provides exactly 19 tools and securely launches the browser;\n5. Discovery drives every visible projection and capability;\n6. operational and agent-memory state is bounded and tenant-scoped;\n7. canonical promotion occurs only through Platform contracts;\n8. the same Customer Zero-verified artifact activates for external users\n   without deployment or code changes.\n"}