Unclassified

Frontend Platform API and Discovery Specification

Status: Derived implementation handoff — required for frontend/backend wiring

Date: 2026-07-28
Authority: ARCHITECTURE_LOCK.md, IMPLEMENTATION_CONTRACT_v1.1.md, and RUNTIME_SUBSTRATE_AND_SURFACE_CONTRACT.md

1. Frontend boundary

apps/web is a Product client. It communicates with the Cloudflare Gateway
only. It does not call Neon, D1, KV, R2, Nango, a provider API, Hermes, or an
internal MCP directly.

Workbench / Canvas / Onboarding
→ typed Gateway client
→ Gateway identity + tenant + RBAC resolution
→ Projection Engine / Platform service / governed command
→ semantic response
→ Product rendering

The single public base URL is NEXT_PUBLIC_IW_API_URL. Release closure must
retire NEXT_PUBLIC_API_BASE_URL and every production fallback to localhost.

1.1 Three Product presentation surfaces

Surface	Controller	Communication
Browser Workbench	IntegrateWise frontend	Typed Gateway client
IW-Spine-Network Plugin	ChatGPT/Codex or compatible AI host	MCP App host bridge to the public IW tools/resources
IW-Spine-Network MCP in an ordinary client	MCP client	Remote MCP transport; text/JSON fallback and Open Workbench link

The Plugin widget is a sandboxed, focused control surface—not a second full
frontend and not a DOM patch. It cannot access host cookies, storage or other
app credentials. The MCP Marketplace lane launches the browser Workbench for
the full tables/pages/canvas experience.

2. Every request and response

Request requirements

Gateway derives authority from the Clerk session. The browser may send display
context such as selected canvas or requested view, but may not authoritatively
send user ID, tenant ID, role, permission, connector credential, policy
decision, or provider scope.

interface GatewayRequestContext {
  // Clerk access token; transported by the typed client.
  authorization: `Bearer ${string}`;
  // Optional correlation for client action tracing.
  "x-iw-correlation-id"?: string;
  // Optional requested rendering context; Gateway validates it.
  requestedView?: string;
}

Response envelope

Every non-streaming semantic response uses an equivalent versioned envelope.

interface GatewayResponse<T> {
  data: T;
  meta: {
    contractVersion: string;
    requestId: string;
    traceId?: string;
    tenantId: string;
    scope: { role: string; permissions: string[] };
    generatedAt: string;
    freshnessAt?: string;
    state: "ready" | "partial" | "degraded" | "pending";
    evidenceRefs?: string[];
    nextActions?: Array<{ capability: string; approval: "none" | "policy" | "human" }>;
  };
}

interface GatewayProblem {
  error: {
    code:
      | "UNAUTHENTICATED"
      | "FORBIDDEN"
      | "NOT_FOUND"
      | "CONFLICT"
      | "VALIDATION_FAILED"
      | "RATE_LIMITED"
      | "DEPENDENCY_UNAVAILABLE"
      | "PARTIAL_EVIDENCE"
      | "INTERNAL";
    message: string;
    requestId: string;
    traceId?: string;
    retryable: boolean;
    remediation?: string;
  };
}

partial and degraded are valid render states. Product must show them; it
must not substitute seed/demo data for a failed live call.

3. Discovery is the frontend’s first read

After sign-in or workspace switch, Product calls the discovery manifest before
rendering navigation or connector-specific capabilities.

Clerk sign-in / workspace switch
→ GET /api/v1/workspace/discovery
→ Gateway resolves tenant, membership, RBAC, configuration, activation,
  connector/schema/capability health and projection manifest
→ Product renders permitted sidebar, Work routes and action availability

interface WorkspaceDiscoveryManifest {
  tenant: { id: string; workspaceId: string; name: string };
  identity: { userId: string; role: string; permissions: string[] };
  navigation: Array<{
    id: string;
    label: string;
    route: string;
    mode: "read" | "operate" | "admin";
  }>;
  work: { routeKey: string; projectionId: string; department: string; industry?: string }[];
  connectors: Array<{ key: string; state: "available" | "connected" | "degraded" | "unavailable" }>;
  capabilities: Array<{
    key: string;
    state: "available" | "degraded" | "unavailable";
    approval: "none" | "policy" | "human";
  }>;
  activation: { state: "not_started" | "in_progress" | "ready" | "blocked"; blockers: string[] };
}

This required Gateway projection contract is now routed by Gateway to the Spine
discovery handler and has real-SQL integration coverage. Production deployment,
cross-tenant/RBAC negative tests and Product acceptance remain open. The
implemented route is still not permission to embed sidebar or connector
availability as client-side constants.

4. Endpoint families

Endpoints are semantic contracts, not table APIs. Route spelling may be
versioned, but the following ownership and request/response semantics are
required.

Product surface / intent	Gateway endpoint family	Backend owner	Response
Bootstrap Product after sign-in	`GET /api/v1/workspace/discovery`	Gateway + Configuration + Activation + Projection	navigation, RBAC, Work routes, connector/capability availability, activation blockers.
Onboarding	`/api/v1/workspace/initialize`; `/api/v1/workspace/configure-domain`; `/api/v1/workspace/configure-rbac`; `/api/v1/workspace/activate`	Gateway + Configuration + Activation	accepted state, next step, hydration/readiness and blockers.
Connector tray	`GET /api/v1/connectors/catalog`; `GET /api/v1/workspace/connectors`; connection health routes	Integration Manager	catalog eligibility, installed connections, health, schema/sync state—never credentials.
Connect/reconnect/revoke	`/api/v1/connectors/{provider}/authorize`; callback; governed connection commands	Integration Manager + credential wall	redirect/connection lifecycle and remediation.
Shared Workbench	`GET /api/v1/projections/{projectionKey}`	Projection Engine	versioned `SharedWorkbench`, provenance, freshness, capabilities and degraded state.
Work views	`GET /api/v1/projections/{projectionKey}?view={viewKey}`	Projection Engine	RBAC-scoped role/department/industry view contract.
Home, Inbox, My Work	`GET /api/v1/projections/home`; `/inbox`; `/my-work`	Projection Engine	composite attention projections, not direct event/work table reads.
Entity / canvas	`GET /api/v1/entities/{entityType}/{entityId}`; projection/canvas route	Projection Engine + Spine read model	permitted entity graph, evidence, timeline, context and layout-safe data.
Active Context	`POST /api/v1/context/assemble` or context included by the entity/projection response	Projection Engine + Continuity	bounded entity/view/evidence/capability context; never raw tables or unrestricted memory.
Communications	`/api/v1/projections/communications/*`	Projection Engine + communication services	scoped conversation continuity, attachments/evidence references and actions.
Documents / knowledge	`/api/v1/knowledge/*`; `/api/v1/search`	Knowledge/evidence service	metadata, retrieval results and signed/authorised artifact access—not raw storage keys.
Twin interaction	`/api/v1/twin/ask`; `/api/v1/twin/assign`; prepared-work/action-plan routes; corresponding public semantic tools	Twin runtime + public semantic contracts	grounded draft/context/plan; no direct execution.
Approve/reject	`/api/v1/approvals/{id}/decision`; governed proposal/capability-run routes	Governance → Hermes	decision, approval token state, receipt and projection invalidation signal.
Platform modules	`/api/v1/platform/{module}/*` or the owning versioned service family	respective Platform service	RBAC-scoped operational projection and governed commands.
Administration	`/api/v1/admin/*`	Administration services	administrative projection; secrets and raw security events remain protected.

These are the target semantic families. A route is not Implemented merely
because it appears in this table.

5. Frontend call sequence

sequenceDiagram
    participant U as User
    participant W as Workbench
    participant G as Gateway
    participant P as Projection Engine
    participant S as Platform services

    U->>W: Sign in or switch workspace
    W->>G: GET workspace/discovery
    G->>S: Resolve identity, tenant, RBAC, activation, availability
    G-->>W: Discovery manifest
    U->>W: Open Home / Work / Platform surface
    W->>G: GET semantic projection
    G->>P: Compose permitted projection
    P->>S: Read canonical truth + bounded cache
    G-->>W: Data + freshness + provenance + available actions
    U->>W: Request consequential action
    W->>G: POST semantic command + correlation ID
    G->>S: Governance → Hermes → connector → re-ingest
    S-->>G: Outcome + invalidation
    G-->>W: Receipt / refreshed projection state

6. Per-click Active Context and Twin activation

Not every DOM click is a Platform or model request. A material click changes
the selected route, entity, work item, decision, signal, document, queue,
proposal or approval.

Material selection
→ resolve projection/entity version
→ assemble or reuse tenant/RBAC-bounded Active Context
→ update selected entity, relationships, timeline, evidence, freshness,
  capabilities and OODA observation state
→ render the Workbench
→ keep Twin silent unless explicitly invoked or a material signal qualifies

Frontend rules:

Deduplicate and cancel stale context requests during rapid navigation.
Cache context only by tenant, workspace, authority fingerprint, projection
version and selected object; invalidate it on the corresponding Gateway
signal.
A click may update lightweight passive observation. It must not
automatically open a Twin panel or start expensive model reasoning.
Ask Your Twin sends the active context reference plus the user's question;
it does not reconstruct organization context in the browser.
Assign Your Twin creates a persistent draft/proposal/assignment, never an
ungoverned provider action.
A qualified proactive signal may render a small inline notice. Deeper Twin
detail still requires review/engagement.
Raw clicks and local hover/scroll telemetry are observations, not canonical
truth. Promotion and retention follow policy.
Frontend tables are entity-shaped projections plus draft working state. They
are not the canonical store.
The autotuning agent may rank, sort, group or suggest projection changes, but
it cannot bypass Triage, approval or governed backend writeback.

7. Discovery and connector expansion

The frontend discovery manifest is a projection of Platform discovery; it is
not provider metadata fetched in the browser.

Connector authenticated
→ Integration Manager discovery run
→ provider schemas, operations, events and scopes classified
→ approved mapping to canonical entities/relationships/capabilities
→ activation and capability availability recalculated
→ workspace discovery manifest and affected projections invalidated
→ Product receives new permitted connector/capability state

Unknown provider structure becomes an extension candidate. It does not create a
new frontend table route or automatically alter canonical schema.

Host-connected applications are not automatically inherited by
IW-Spine-Network. Discovery records one of three origins:

host_composed: the host can use another app in the current conversation;
host_delegated: the host exposes a supported capability and the user/admin
grants a persistent IW binding;
iw_direct: the user authorizes the provider in Integration Manager.

The frontend groups duplicate provider/account connections only when tenant,
account, user, provider workspace, authority and provenance match. It always
shows origin and precedence.

8. Frontend implementation rules

Use one typed Gateway client and one public API base URL.
Call discovery at authentication/workspace boundaries; cache only as bounded,
versioned UI state and invalidate on Gateway signals.
Drive sidebar and Work routes from discovery/role config, not from provider
names, business domains or direct database assumptions.
Bind each surface to a projectionId, contract version, loading state,
partial/degraded state, and permitted commands.
Use server-issued identifiers and evidence references. Do not expose provider
credentials, raw object keys, internal MCP routes, or internal Pool tools.
For canvas data, render safe semantic shapes. JSON is display data, not a
query language against Fortress tables.
Persist an intake draft locally only as a draft. Submit it through Gateway so
the artifact/event/provenance/triage path is recorded.
Treat operational-memory and agent-memory records as staged, promoted
entities. The frontend may display and edit drafts, but Fortress persistence
only happens after triage classification, promotion queue placement and human
approval.

9. Entity tables and memory promotion

User action / external event / agent observation
→ Frontend creates or updates an entity-shaped draft/table/canvas projection
→ Gateway emits a semantic event or command
→ Triage classifies, links, deduplicates and scores it
→ Promotion queue stages candidate operational memory or canonical truth
→ Human approval decides whether it is promoted
→ Fortress writeback occurs through the governed backend writer
→ Projection invalidation refreshes the frontend tables and canvases

The frontend repo therefore holds:

projection contracts for entity tables and canvases;
draft working state for agent memory and operational memory;
typed Gateway calls for create/update/promote/approve flows; and
rendering logic for the resulting RBAC-scoped projections.

The frontend repo does not hold:

canonical truth ownership;
direct Neon write authority;
provider credentials;
promotion authority; or
an alternate schema that bypasses the backend.