Unclassified

Platform, Product, Data and Projection Reference

Status: Derived implementation reference — verification checkpoint, not a new architecture authority

Date: 2026-07-28
Authority: ARCHITECTURE_LOCK.md, as implemented by IMPLEMENTATION_CONTRACT_v1.1.md. Where this document conflicts with either, the canonical documents win.

1. Purpose and checkpoint

This is the single traceability reference for the question: do we have the tables, entity mappings, tenant/person model, connector expansion, storage split, projections, Product-to-Platform calls, and Workbench views required to operate IntegrateWise?

State	Meaning
Defined	Frozen or approved contract exists.
Implemented in repository	Migration, package, route, or test is present.
Live verified	Applied to the intended environment and proven by tenant-isolated acceptance tests.

The repository establishes much of the first two states. It does not prove that migration 035 has been applied to Neon, that all bindings are live, or that the complete flow has passed production acceptance. Those remain go-live gates. A static review also found that the migration creates governance_policies but later seeds spine_governance_policies; that name mismatch must be corrected and the full migration run in a disposable Neon-compatible database before it is treated as deployable.

2. The one data path

flowchart LR
    P["Product: Onboarding and Workbench"] -->|"Clerk session + semantic request"| G["Gateway"]
    G --> C["Configuration / Integration / Activation"]
    C --> X["Provider connector credential wall"]
    X --> L["Pipeline: load, normalize, promote"]
    L --> N["Neon Fortress: canonical Spine truth"]
    L --> R["R2: raw payloads, files, immutable evidence"]
    N --> PE["Projection Engine"]
    R --> PE
    PE --> D["D1 / KV: bounded runtime and cache"]
    PE -->|"SharedWorkbench contract"| G
    G --> P
    P -->|"intent only"| G
    G --> GOV["Governance → approval token → Hermes"]
    GOV --> X

The browser never uses a provider token, queries a provider model, or writes Neon directly. The Pipeline is the sole canonical Spine writer; Projection Engine is the sole SharedWorkbench composer.

3. Database and storage split

Store / boundary	What belongs there	Access rule
Neon Fortress (canonical)	Tenant identity/membership, connector metadata and connection records, canonical entities, relationships, provenance, work, governance, activation, events, sync, projection definitions and snapshots, audit, promoted outcomes.	Gateway and internal Platform services only; canonical writes only through Pipeline promotion.
R2 evidence store	Provider raw payloads, uploads, attachments, documents, immutable evidence, large transcripts.	References/hashes are held in Neon; access is policy-checked through Platform.
Vectorize / AI Search	Embeddings and retrieval indexes.	Retrieval aid only; never canonical truth.
D1 operational state	Idempotency, active context, edge-operational indexes, runtime state and bounded projection snapshots.	Reconstructable from canonical services; never a business system of record.
KV	Short-lived projection cache, sessions, connector health/status, invalidation keys.	Time-bounded and invalidatable; never truth.
Provider / Nango credential wall	Tenant-scoped OAuth authorisation and secrets.	Opaque reference only in Platform records; no credential reaches Product, MCP public tools, or AI prompts.

There is no separate customer database schema per tenant in the canonical design. Tenant-owned rows carry tenant_id, are resolved from the Clerk session by Gateway, and must be scoped in every query, write, cache key, event, and evidence reference.

3.1 Three clean environments

These are separate environments with separate credentials, bindings, data and
release controls. They are not three names for the same database or deployment.

Environment	Purpose	Allowed data and identities	Platform and Product rule
Development	Engineering build, local development, automated tests and disposable integration testing.	Synthetic/test tenants, test provider applications and test credentials only.	Engineers may use selected fixed development infrastructure. Product builds may be local, preview, Vercel or Netlify, but always call the Development Gateway—not a live data store.
Customer Zero	IntegrateWise's own real operational tenant; the first production-shaped operating environment.	IntegrateWise people, work, consented real connections and real operational data under tenant `iw-customer-zero`.	Uses the same production Platform contracts as customers, but its own tenant-scoped records, credentials, connector bindings, evidence and audit. It is never a shared test tenant and never a source of demo fallback.
Customer Production	Each external customer's live operating environment.	Only that customer's verified members, consented provider connections, canonical Spine data, evidence and governed actions.	Customer chooses connectors and permitted capabilities through the tray. The customer does not choose or access Platform infrastructure, another tenant's data, Customer Zero credentials or development resources.

Non-negotiable separation

Separate Cloudflare accounts/namespaces or explicitly isolated bindings for
D1, KV, R2, queues, Vectorize, Durable Objects and Worker environment
variables; no shared mutable test/production binding.
Separate Neon databases or projects and separate migration ledgers for
Development, Customer Zero and Customer Production. Customer Production may
use one canonical production database only when tenant isolation is enforced
end-to-end; it is still logically and operationally separate from Customer
Zero.
Separate Clerk instances/keys or clearly separate environments, OAuth
provider applications/redirects, Nango connections, secret stores, webhook
endpoints and DNS routes. A credential or webhook from one environment must
be rejected by the others.
Promotion direction is one-way: Development → Customer Zero validation →
Customer Production release. Production data, credentials and connector
bindings never flow back to Development.
Product frontends can be deployed independently in Development and preview
environments, but every environment targets only its matching Gateway. The
Platform Fortress, Gateway, Spine, governance and credential wall remain
Platform-owned services.

3.2 Published product name and packages

The public distribution identity is IW-Spine-Network.

The naming hierarchy is deliberately not a rename of the product:

IntegrateWise                         = product and company brand
IntegrateWise Workbench               = the user’s one operational surface
IW-Spine-Network                      = public distribution identity
IW-Spine-Network Plugin               = plugin marketplace/directory package
IW-Spine-Network MCP                  = MCP marketplace/registry package
IW Spine Tools                        = the public MCP technical interface
Continuity                            = a Workbench module and outcome

In product language: “IntegrateWise Workbench runs on
IW-Spine-Network.” This preserves the frozen product name while giving both
distribution lanes one identity.

Name	Use it for	Do not use it for
IntegrateWise	Company and full product brand.	An internal engine-only or connector-only label.
IntegrateWise Workbench	The user-facing operational product surface.	A distinct product that competes with or replaces IntegrateWise.
IW-Spine-Network Plugin	Plugin marketplace/directory listing that packages an MCP-backed app, focused interactive UI, workflow skills and optional templates.	A claim that the plugin inherits every other host-app credential.
IW-Spine-Network MCP	MCP marketplace/registry listing for the remote server, optional focused MCP App UI and browser Workbench launch.	The internal MCP Pool.
IW Spine Tools	The exact public, OAuth-protected 19-tool semantic MCP interface behind both packages.	The marketplace artifact name or the 55-tool internal Pool.
Continuity	A Workbench product module and user outcome: retained, governed work context.	The plugin or company/product name.
IW Continuity Bridge	Historical/superseded terminology only.	Any new marketplace listing, UI label, endpoint, package or documentation title.

The marketplace listing should therefore read:

Plugin listing: IW-Spine-Network Plugin
Plugin experience: Embedded host control surface over the IW MCP app
MCP listing: IW-Spine-Network MCP
MCP experience: Remote 19-tool server + Open Workbench browser action
Technical interface: IW Spine Tools
Technical identifier: iw-spine-network

Plugin installation applies the Customer Zero-proven reference activation
profile to an isolated customer tenant. It does not share or copy the Customer
Zero tenant. The AI host can compose applications only when it exposes them and
the user/admin grants authority; persistent discovery requires an explicit host
delegation or IW connector binding.

4. Actual Neon Fortress schema inventory

migrations/035_canonical_spine_schema_fortress.sql contains 114 CREATE TABLE IF NOT EXISTS statements. It is the main consolidated schema candidate and defines the following functional groups.

Domain	Principal tables	Why they matter
Identity and tenancy	`spine_organizations`, `spine_workspaces`, `spine_users`, `spine_memberships`, roles, permissions, role bindings, consent grants, API-key references	Separates person identity, membership, organisation, workspace and authority.
Configuration and activation	`platform_config_layers`, compiled configs, feature flags, entitlements, activation runs/steps, hydration plans	Makes configuration and activation explicit Platform records.
Connector network	`spine_connector_catalog`, versions, installations, `integration_connections`, connection health, provider schemas, schema mappings, cursors, webhook endpoints	Holds catalog-to-tenant installation-to-connection-to-schema lineage.
Canonical Spine	typed entity tables from `037_pure_entity_spine_tables.sql` (`spine_persons`, `spine_projects`, `spine_tasks`, etc.), compatibility `spine_entities`, entity versions, `spine_external_identities`, relationships, relationship versions, provenance, evidence links	Pure entity-family tables are the forward canonical model; `spine_entities` remains a compatibility path during cutover.
Schema expansion	schema modules, versions, field definitions, relationship definitions, lifecycle definitions/transitions	Enables additive domain/entity expansion without hard-coding provider models into Product.
Work and operations	work items, decisions, approvals, notifications, timeline, calendar, meetings, calls, messages, threads	Holds tenant operational activity and governed decisions.
Projection and Workbench	projection definitions, versions, bindings, field rules, view rules, capability bindings, snapshots, tuning profiles/events	Stores governed projection contracts and cached snapshot references—not UI-owned truth.
Capability and governance	capabilities, versions, provider/policy bindings, runs/steps/outcomes, policies, decisions, tokens, audit	Enforces the approval-to-Hermes execution path.
Event, continuity and sync	event types/events/subscriptions/delivery, continuity, sync runs/mutations/conflicts/verifications	Supports the repeat and reconciliation portions of the pipeline.
Knowledge, memory, marketplace and MCP	memory, knowledge/evidence records, marketplace/MCP server and install records	Holds policy-controlled references rather than exposing raw credentials or direct provider tables.

Person and entity rules

A product user is spine_users.user_id, linked to identity_subject (the Clerk subject), and gains tenant scope through spine_memberships.
A business person/contact/customer belongs in spine_persons, not as a second browser-user account. spine_entities may continue to mirror or bridge legacy runtime paths until typed-table cutover completes.
A provider record maps through spine_external_identities using the unique (connection_id, provider_object_type, external_id) identity. This prevents one provider object from being mistaken for a new entity on later syncs.
Canonical entity uniqueness is scoped by (tenant_id, workspace_id, entity_type, canonical_key). Relationships are tenant-scoped and point to canonical entity IDs.
Per-person and per-role views are projections, not copies of person data. A user’s membership, role, policy, permitted entities and current context determine the response.

5. Connector mapping and expansion algorithm

The catalog is global and read-only. A tenant obtains an operational connector only after the following resolution succeeds:

catalog connector
→ installation for tenant/workspace
→ provider consent and opaque credential reference
→ integration connection
→ provider-schema discovery
→ approved schema mapping to Spine entity types
→ initial sync and Pipeline normalization
→ canonical entity / relationship / provenance promotion
→ projection invalidation and activation

Mapping	Current implementation evidence	Required semantics
Catalog → version	`spine_connector_catalog`, `spine_connector_versions`	Provider-neutral connector capability and compatibility contract.
Tenant/workspace → install	`spine_connector_installations`	Installed state and tenant-owned configuration.
Install → credential-backed connection	`integration_connections`	Tenant, workspace, connector, external account and opaque credential-vault reference.
Connection → discovered object model	`integration_provider_schemas`	Provider object schema/version discovered under that connection.
Provider object → canonical entity	`integration_schema_mappings`	Field transform and target Spine entity type.
Connection/object → cursor/webhook/sync	cursors, webhook endpoints, sync runs/mutations/conflicts	Incremental change, provenance, reconciliation and health.

Expansion algorithm

Gateway resolves Clerk identity, membership, active tenant and role; it never accepts these as an authoritative browser override.
Integration Manager verifies the connector catalog entry and starts provider consent. Provider credentials become an opaque vault/Nango reference.
Configuration Manager applies tenant policy, allowed scopes, selected domains and schema modules; Activation Hub creates the activation and hydration plan.
The connector discovers provider objects and writes provider schemas. A versioned mapping translates provider fields to canonical entity types, fields and relationship definitions.
Pipeline performs load → normalize → validation/triage → identity resolution → canonical promotion. It upserts the canonical entity and external identity, records relationship/provenance/evidence, and writes sync state.
Projection Engine invalidates affected cache keys and recomposes only the permitted role/person/tenant projection. Stale, revoked or ambiguous connections are fail-closed and excluded from projections, Twin context, capability resolution and execution.

Known binding gap

The approved strict operational tuple is:

(user_id, account_id, tenant_id, provider_key, provider_workspace_id,
 connector_binding_id, spine_connection_id, schema_binding_set)

The repository documentation explicitly says that dedicated connector_bindings and connector_schema_bindings runtime migrations are Approved, not Implemented. Migration 035 supplies closely related installation, connection, provider-schema and schema-mapping records, but it does not replace the need to decide and implement the strict binding records before declaring tenant connector activation complete.

6. Projection canvas and product views

The Product is one Workbench. It consumes semantic projections rather than tables. The canonical SharedWorkbench contains tenant/workspace identity, role and domain, permitted entity groups, relationships, timeline, knowledge, signals, capabilities, governance decisions, available actions, Twin context, readiness and provenance.

View / canvas	Projection inputs	Product response
Onboarding and activation	identity, organisation/tenant, configuration, connector install/health, hydration plan	next required setup action, readiness and explicit failure state.
Role Workbench / operational canvas	permitted entities and relationships, work, timeline, signals, knowledge, readiness	one role-specific shared operational surface.
Entity 360	a selected canonical entity, its relationships, evidence, timeline, signals and permitted knowledge	an evidence-backed person/account/work/entity view.
Organizational Memory / Company Wiki	promoted organizational memory, knowledge documents, brainstorming sessions, policies, rituals, decisions, linked entities, evidence, timeline	company front door and operating handbook surface, rendered as RBAC-scoped document-like pages, linked subpages and embedded views.
Integration Manager	global catalog plus tenant installation, connection, schema, sync, webhook and health state	connector tray, connect/reconnect/repair/pause/revoke flows.
Configuration Manager	config layers, compiled config, policies, schema and role context	validated tenant configuration—not direct database editing.
Activation Hub	activation run/steps, hydration plan, connector readiness, schema coverage	activation progress and go/no-go reasons.
Governance	decision, proposal, policy, approval token and audit state	review/approve/reject; no direct provider action.
Network Graphs and Continuity	canonical entities, relationships, events, evidence, permitted memory	scoped graph and history views with provenance.

packages/projection-engine/ is the sole composer. apps/web contains projection consumers and view composition; it must not calculate alternative KPI truth or join provider-specific records in the browser.

7. Product-to-Platform API contract

All product calls go to the Gateway base URL. Current code has a split configuration (NEXT_PUBLIC_API_BASE_URL in the legacy Gateway client and NEXT_PUBLIC_IW_API_URL in the shared environment helper); release closure requires one public Gateway variable and removal of localhost fallback outside local development.

Product intent	Gateway contract family	Platform work	Response to Product
Start onboarding	`POST /api/v1/workspace/initialize`	resolve/create tenant-workspace context	tenant/workspace identifiers and next step.
Set role/domain	`POST /api/v1/workspace/configure-domain`, `/configure-rbac`	compile configuration and role policy	accepted configuration/version or field-level errors.
Open connector tray	`GET /api/v1/connectors/catalog`	read global catalog + tenant eligibility	permitted connectors and install state.
Connect a provider	`GET /api/v1/connectors/{provider}/authorize`; callback	consent, credential wall, create connection/binding	redirect/connection state—never a provider credential.
Activate tenant	`POST /api/v1/workspace/activate`; hydrate connectors	create activation/hydration work, schedule pipeline	activation state, coverage, readiness, actionable blockers.
Render Workbench	`GET /api/v1/workspace/projection/{department}`	resolve identity/policy, compose SharedWorkbench	versioned, scoped projection with provenance/freshness/degradation.
Render entity detail	`GET /api/v1/entity360/{entityId}`	assemble permitted entity projection	entity view with evidence and state.
Browse integrations	workspace connector/status endpoints	integration health/schema/sync state	no secret material; repair/reconnect requirements.
Ask/assign Twin	semantic Twin/public MCP contracts	read permitted context; draft only	grounded response/draft; no action executed.
Approve action	approval/proposal route	governance → token → Hermes → connector	plan, approval state, execution receipt, then refreshed projection.

Every semantic response must contain (or be tied to) tenant scope, permission scope, version, freshness, provenance/evidence references and a clear partial or degraded state. Failed live access must not become demo/seed content.

8. Verification matrix and release checkpoint

Checkpoint	Defined	Repository evidence	Live verification still required
Fortress canonical schema	Yes	migration 035 (114 tables)	Correct the `governance_policies` / `spine_governance_policies` seed mismatch, run the full migration in a disposable Neon-compatible database, then apply to Neon and inspect schema/version.
Tenant/person/entity isolation	Yes	tenant IDs, membership tables, entity uniqueness and indexes	Cross-tenant negative tests and Clerk-to-tenant resolution tests.
Connector-to-Spine mapping	Yes	catalog/install/connection/schema/mapping/sync tables	Tenant OAuth, schema discovery, cursor/webhook, revocation and reconnection tests.
Strict connector binding tuple	Approved	documentation only	Implement migrations and Gateway enforcement.
Projection canvas	Yes	Projection Engine, contracts, web projection consumers	Permission, freshness, invalidation and partial-evidence acceptance tests.
Product-to-Platform calls	Yes	Gateway client/onboarding and projection routes	One production Gateway base URL, auth, error and correlation tests.
DB storage split	Yes	implementation contract and service boundaries	Verify D1/KV/R2 bindings are isolated per environment and no direct Product DB path exists.
Governed actions	Yes	capability/governance schema and contracts	approval-token and Hermes-only end-to-end test with a non-destructive connector action.

9. Required evidence before testing-environment event

Correct the migration-035 governance_policies / spine_governance_policies seed mismatch, run it in a disposable Neon-compatible database, then record a migration ledger showing it applied successfully to the named Neon environment with its migration version and table count.
Implement and migrate the strict connector binding/schema-binding model, or explicitly ratify the migration-035 records as its replacement and update the binding decision accordingly. Do not leave both models ambiguous.
Publish a tenant-isolation test report covering user, person entity, connector, projection, cache and evidence access.
Demonstrate one real connector through consent → schema mapping → initial hydration → delta sync → canonical entity and provenance → Workbench projection → revoke/fail-closed.
Demonstrate Product calls only the Gateway in the testing environment, with no localhost fallback, direct provider access or direct Neon path.
Capture the shared Workbench contract and the actual rendered views for at least one role, one person/entity, Integration Manager, Activation Hub and Governance.

10. Primary repository anchors

migrations/035_canonical_spine_schema_fortress.sql
docs/architecture/IMPLEMENTATION_CONTRACT_v1.1.md
docs/wiki/12-connectors-integration-manager-and-spine-network.md
docs/wiki/07-projection-engine-and-shared-workbench.md
packages/projection-engine/
packages/contracts/src/projections/
services/gateway/src/projections.ts
apps/web/src/lib/onboarding-api.ts
apps/web/src/lib/gateway-client.ts