Unclassified

Browser Frontend and MCP Product Code Brief

Status: Implementation briefing
Date: 2026-07-29
Audience: Frontend, Platform, MCP, Customer Zero and release engineers
Governing specifications:
CUSTOMER_ZERO_TO_EXTERNAL_PRODUCT_AND_MARKETPLACE_SPEC.md,
FRONTEND_PLATFORM_API_AND_DISCOVERY_SPEC.md and
IW_SPINE_NETWORK_PLUGIN_AND_MCP_MARKETPLACE_CONTRACT.md

1. Product to build

The frontend repository owns the complete IntegrateWise browser Product:

onboarding;
full Workbench;
tables, records, pages and canvases;
Home, My Work, Communications, Personal and Work projections;
permitted Platform and Administration modules;
contextual Silent Twin;
Connector Marketplace and activation;
approvals and execution status;
organizational and operational-memory projections.

It is implemented for Customer Zero first and then promoted as the external
browser Product from the same versioned codebase.

IW-Spine-Network Plugin
→ focused UI inside ChatGPT/Claude/compatible host
→ optional Open Workbench

IW-Spine-Network MCP
→ remote 19-tool protocol endpoint
→ text/JSON or focused widget in MCP client
→ Open Workbench
→ complete browser Product from the frontend repository

The Plugin and browser are two presentations of the same work, context, Spine
and governed capabilities. They are not separate products or sources of truth.

2. Browser Product versus Plugin Product

Concern	Plugin/hosted application	Browser frontend
Primary location	Inside ChatGPT, Claude or compatible host	Standalone browser
Controller	AI host owns conversation/model	IntegrateWise owns browser experience; Platform model policy owns IW reasoning
Experience	Focused current work, context, search, proposal, approval and progress	Complete Workbench, tables, pages, canvases, connectors, Platform and Administration
Transport	Host MCP App bridge	One typed Gateway client
Full Workbench	Launch target only	Primary surface
Host-connected apps	Host composition or explicit delegation	Shows persisted delegated bindings and IW direct connections
Product state	Bounded hosted operational state	Bounded browser/server operational state
Canonical truth	Platform only	Platform only
Internal MCP Pool	Never published	Customer Zero operator module only; never ordinary customer access

The Plugin must not attempt to reproduce the entire browser Workbench. The
browser frontend must not depend on an AI host to function.

3. MCP marketplace relationship

IW-Spine-Network MCP is the protocol package. The frontend repository supplies
the complete browser destination associated with that package.

User finds IW-Spine-Network MCP
→ connects remote MCP
→ completes OAuth and consent
→ Gateway resolves/creates logical tenant, workspace and membership
→ client receives exact 19-tool catalog
→ client can use text/JSON or focused MCP widgets
→ Open Workbench creates a secure handoff
→ browser frontend resumes the permitted tenant/work context

The MCP server remains Platform-owned. The frontend repository does not host an
independent copy of the public tool server unless the deployment manifest
explicitly identifies a thin proxy that preserves the same Platform contract.

4. No deployment during onboarding

The browser application and Platform services are already deployed.

Browser signup or MCP Workbench launch performs logical provisioning only:

authenticate
→ resolve/create tenant_account_id
→ resolve/create tenant_id
→ resolve/create workspace and membership
→ allocate stable spine_network_id
→ apply activation-profile definitions
→ initialize bounded operational/frontend state
→ return workspace Discovery
→ compose and render Workbench

It does not deploy:

a new frontend;
a new Worker;
a new database;
a new queue or bucket;
a new MCP server;
a copy of Customer Zero.

All initial external users run inside the IntegrateWise-managed shared SaaS
environment with separate logical tenant boundaries.

5. Customer Zero and external profiles

The frontend codebase produces one browser artifact with two
server-authoritative profiles:

Concern	Customer Zero browser	External browser
Profile	`cz-mcp-workbench`	`external-mcp-workbench`
Tenant	`iw-customer-zero` after membership proof	Dynamically resolved logical tenant
Entry	Direct browser, private MCP or Plugin handoff	Direct browser, public MCP or Plugin handoff
Data	IntegrateWise operations	Tenant-isolated customer data
Connections	IntegrateWise-owned	Customer-consented
Internal operations	RBAC-gated	Not exposed
Public tools	Exact 19	Exact 19
Navigation	Customer Zero RBAC projections	Customer RBAC × role × department × industry × availability
Approval	Mandatory	Mandatory

Do not build separate Customer Zero and external frontends. Do not maintain
long-lived profile branches.

6. Frontend repository ownership

6.1 Browser application

The repository owns:

authentication and marketplace-origin presentation;
onboarding and activation progress;
discovery-driven navigation;
projection rendering;
entity tables and records;
document/page rendering;
editable Workbench canvases;
drafts and optimistic presentation;
contextual Twin interactions;
Four Buttons;
Connector Marketplace;
approval and execution receipts;
responsive and accessible behavior;
browser error, partial, stale and degraded states.

6.2 Server-side Product runtime

Where the frontend repository includes route handlers or a backend-for-frontend,
that server-side Product runtime may own bounded, tenant-scoped state:

browser session handoff records;
short-lived projection caches;
layout and user-preference state;
draft and autosave state;
event outbox/inbox;
idempotency records;
pending upload metadata;
agent scratchpad and working-memory drafts;
operational-memory candidates;
notification/read cursors;
resumable UI workflow state.

This state is non-authoritative, bounded and reconstructable. Sensitive durable
state must remain server-side; it must not be placed in browser local storage.

6.3 Browser client

The browser itself may hold:

selected route/entity/view;
unsaved form state;
temporary canvas edits;
bounded query cache;
accessibility and display preferences;
short-lived handoff/session references.

Tenant switches, sign-out and permission reductions must clear affected
caches immediately.

7. What remains Platform-owned

The frontend does not own:

identity or tenant authority;
provider credentials;
connector runtimes;
deterministic normalization;
Operational Spine authority;
Triage promotion policy;
Canonical Spine/Fortress;
canonical memory;
Projection contract authority;
Twin model routing;
Capability registry/resolver;
Governance or approval tokens;
Hermes;
provider execution;
internal MCP Pool;
public MCP server authority.

The frontend consumes semantic contracts; it does not know the internal service
topology.

8. Required repository shape

apps/
  workbench/                    # complete browser Product
  product-runtime/              # optional BFF/route handlers
packages/
  ui/                           # shared components and design tokens
  platform-client/              # one generated Gateway client
  projection-renderer/          # entity/page/table/canvas projections
  workbench-state/              # bounded drafts/preferences
  operational-state/            # server-side Product operational store
  agent-working-memory/         # scratchpad/candidate contracts
  marketplace-handoff/          # Plugin/MCP browser handoff
profiles/
  customer-zero/
  external/
tests/
  contract/
  discovery/
  rbac/
  tenant-isolation/
  handoff/
  operational-memory/
  approval/
  browser-e2e/

No profile directory contains credentials or fixed tenant authority.

9. Secure Plugin/MCP-to-browser handoff

The Plugin or MCP client must not place access tokens, credentials, tenant IDs,
raw context or provider data in a browser URL.

9.1 Handoff creation

Plugin/MCP client requests Open Workbench
→ Platform verifies OAuth identity and tenant membership
→ Platform creates short-lived one-time handoff
→ handoff stores tenant, workspace, installation, context_ref and return policy
→ client receives opaque handoff_id + approved Workbench URL

9.2 Browser exchange

browser opens /handoff/{opaque_id}
→ browser authenticates with Clerk if required
→ frontend server exchanges one-time handoff with Gateway
→ Gateway verifies user, tenant, workspace, expiry and consumption state
→ handoff is consumed
→ browser receives normal session-bound Discovery
→ Workbench opens the permitted projection/context

Handoff requirements:

opaque and unguessable identifier;
short expiry;
one-time consumption;
server-side storage;
installation and user binding;
intended tenant/workspace binding;
replay rejection;
audit event;
no bearer token in query parameters;
no raw context or secrets in URL;
safe fallback to normal login if expired.

10. Direct browser entry

The browser is also a normal daily-use Product and does not require MCP or
Plugin entry.

user opens IntegrateWise
→ Clerk sign-in
→ Gateway resolves tenant/workspace/membership
→ GET /api/v1/workspace/discovery
→ render permitted Workbench

Marketplace origin is preserved only as onboarding/resume context. It does not
change tenant authority or create a separate Product.

11. Discovery is the first read

After authentication, workspace switch or handoff exchange:

GET /api/v1/workspace/discovery
→ identity + tenant + membership
→ RBAC and entitlements
→ activation profile
→ navigation and projections
→ connector and capability state
→ marketplace installation state
→ partial/degraded blockers

The frontend does not render authoritative navigation from hard-coded provider
lists or department schemas.

Every visible module must map to:

projectionId;
contract version;
permitted read mode;
permitted commands;
capability requirements;
approval requirements;
loading/partial/degraded/forbidden behavior.

12. One frontend-to-Platform client

NEXT_PUBLIC_IW_API_URL
→ typed Gateway client
→ Clerk token forwarding
→ correlation and idempotency
→ response validation
→ normalized error states

Components do not construct service URLs.

The browser never calls:

Neon;
D1, KV or R2 directly;
Nango or credential storage;
provider APIs;
Hermes;
internal Workers;
internal MCP Pool.

13. Workbench and projection behavior

The Workbench is one surface. Role, department and industry select RBAC
projections over tenant-level entities; they do not create department schemas.

The frontend renders:

entity tables;
record detail and timelines;
related entities and evidence;
documents and knowledge;
tasks, queues, approvals and notifications;
pages and database-style views;
editable canvases;
lifecycle and activity projections;
organizational-memory projections.

CRUD behavior:

user edits projection/draft
→ frontend validates local shape
→ semantic command sent to Gateway
→ Platform returns accepted/pending/rejected state
→ UI displays receipt
→ canonical outcome appears only after governed lifecycle

The browser never reports canonical success before the Platform returns the
corresponding accepted/promoted outcome.

14. Twin, agents and models

In the browser, IntegrateWise—not an external host—owns the Product interaction
loop.

Twin is a capability of the Workbench, silent by default.
Material clicks assemble or reuse Active Context.
Twin participates at THINK when explicitly asked or when a material signal
qualifies.
Ask your Twin explains or prepares.
Assign your Twin creates a governed assignment/proposal.
Approve Twin's Action is the explicit human authority boundary.

The browser frontend does not select model vendors. Configuration/model policy
resolves models, fallbacks, privacy, rate limits and budgets.

Agent working-memory state may be staged in the Product operational runtime.
Promoted user or organizational memory remains Platform-owned.

15. Operational and agent memory

State	Frontend/Product runtime	Platform
Unsaved draft	Owns temporarily	Not yet received
Canvas/layout preference	Owns bounded state	Optional governed profile sync
Agent scratchpad	Owns bounded working state	Not canonical
Active Context cache	Owns tenant/RBAC-keyed projection cache	Supplies authoritative context contract
Operational-memory candidate	Stages and submits	Triage classifies and queues
Canonical memory	Displays projection only	Owns through governed promotion
Canonical entity truth	Displays/edits semantic projection	Owns through governed writers

Synchronization is command/event based:

frontend draft or agent outcome
→ Product outbox
→ Gateway semantic event/command
→ Pipeline + Triage
→ Operational Spine
→ promotion queue
→ human/policy decision
→ Governed Spine Writer
→ Canonical Spine
→ projection invalidation
→ frontend refresh

There is no frontend-database-to-Fortress replication path.

16. Connector and application behavior

The browser shows a unified connection/network projection with explicit origin:

iw_direct;
host_delegated;
host_composed.

iw_direct connections are persistent IntegrateWise connections.

host_delegated connections are persistent only when the host, user/admin and
IW all support and authorize the delegation contract.

host_composed is a host/session capability. The browser may show its last
known availability when linked to the same installation, but it must not claim
direct credentials or persistent synchronization.

When data is missing, the browser presents Connector Marketplace rather than
silently selecting a provider.

17. Browser states

Every major surface supports:

loading;
empty;
ready;
stale;
partial;
degraded;
unauthorized;
forbidden;
conflict;
pending approval;
execution in progress;
reconciled;
revoked.

Live failure never falls back silently to demo or seed data.

18. Customer Zero implementation sequence

Build the browser shell and one typed Gateway client.
Implement real Clerk/Gateway identity and logical tenant allocation.
Make Discovery the first read.
Implement Customer Zero RBAC projections.
Implement bounded frontend/Product operational state.
Implement entity tables, records, pages and canvases.
Implement Active Context, Twin and Four Buttons.
Implement Connector Marketplace and activation status.
Implement approval, execution receipt and reconciliation.
Implement MCP and Plugin one-time Workbench handoff.
Run Customer Zero daily work through the browser.
Activate the same artifact for a clean external logical tenant.

19. MCP and browser release gates

Before MCP marketplace publication:

MCP protected-resource and OAuth metadata are correct;
exact 19-tool catalog is verified;
ordinary-client text/JSON fallback is meaningful;
Open Workbench creates a secure one-time handoff;
expired/replayed/cross-tenant handoffs fail;
browser Discovery resolves the same tenant and permissions;
Customer Zero and external profiles use the same build;
no Product code calls Platform internals directly;
operational-memory promotion is governed;
browser works without ChatGPT or another AI host.

20. Later dedicated-partition movement

The browser URL and Product artifact remain stable if a logical tenant later
moves from shared infrastructure to a dedicated partition.

Gateway resolves the tenant and routes requests to the approved partition. The
browser does not know the database, Worker, queue, bucket or model location.

21. Stop-ship conditions

Do not release if:

browser onboarding deploys infrastructure;
external users are placed inside iw-customer-zero;
tenant, role or permission authority is accepted from browser state;
MCP or Plugin puts bearer tokens or tenant IDs in Workbench URLs;
frontend directly calls a database, provider, Hermes or internal MCP;
navigation or schema is partitioned by department;
the browser requires an AI host to operate;
agent working memory writes canonical truth directly;
Product operational state becomes an unbounded competing Spine;
UI reports provider/canonical success before reconciliation;
internal MCP Pool is visible to ordinary external users.

22. Definition of done

The frontend code briefing is satisfied when:

one browser artifact serves Customer Zero and external profiles;
direct browser, Plugin handoff and MCP handoff resolve the same logical
tenant and Workbench;
the complete Workbench functions independently of an AI host;
MCP provides exactly 19 tools and securely launches the browser;
Discovery drives every visible projection and capability;
operational and agent-memory state is bounded and tenant-scoped;
canonical promotion occurs only through Platform contracts;
the same Customer Zero-verified artifact activates for external users
without deployment or code changes.