Frontend → Operational Spine → Canonical Spine Mapping

Date: 2026-07-31
Purpose: Every unmapped and unwired path becomes visible.
Basis: Three parallel deep audits of frontend fetches, Gateway routes, and service store access.

---

1. The Three Layers

┌─────────────────────────────────────────────────────────────┐
│  FRONTEND (apps/web)                                        │
│  apiFetch() → NEXT_PUBLIC_IW_API_URL → Gateway              │
│  GatewayHttpClient → NEXT_PUBLIC_API_BASE_URL → Gateway     │
│  spineClient (Supabase-like) → gateway-adapter → Gateway    │
├─────────────────────────────────────────────────────────────┤
│  GATEWAY (services/gateway)                                 │
│  51-entry ROUTES table → service bindings (Fetcher)         │
│  Direct D1/KV reads for workspace discovery, entities       │
├─────────────────────────────────────────────────────────────┤
│  SERVICES                                                   │
│  spine · pipeline · knowledge · intelligence · mcp-connector │
│  continuity · workflow · hermes · mcp-pool · webhook-ingress│
├─────────────────────────────────────────────────────────────┤
│  STORES                                                     │
│  D1 (Operational) · Neon (Canonical) · KV · R2 · Queues · DO│
└─────────────────────────────────────────────────────────────┘

---

2. Frontend → Gateway (Complete Route Map)

2.1 API Client → Gateway Routes

Frontend Client	URL Path	Gateway Route	Target Service	Status
apiFetch()	/api/v1/workspace/discovery	Handled directly	Gateway + Spine	✅ WIRED
apiFetch()	/api/v1/workspace/connectors	/api/v1/workspace/*	BFF (workflow)	✅ WIRED
apiFetch()	/api/v1/workspace/connectors/catalog	/api/v1/workspace/*	BFF	✅ WIRED
apiFetch()	/api/v1/workspace/connectors/nango-session	/api/v1/workspace/*	BFF	✅ WIRED
apiFetch()	/api/v1/workspace/profile	/api/v1/workspace/*	BFF	✅ WIRED
apiFetch()	/api/v1/workspace/spine-config	/api/v1/workspace/*	BFF	✅ WIRED
apiFetch()	/api/v1/workspace/tenant-products	/api/v1/workspace/*	BFF	✅ WIRED
apiFetch()	/api/v1/workspace/user-roles	/api/v1/workspace/*	BFF	✅ WIRED
apiFetch()	/api/v1/workspace/register-connector	/api/v1/workspace/*	BFF	✅ WIRED
apiFetch()	/api/v1/workspace/initialize-spine	/api/v1/workspace/*	BFF	✅ WIRED
apiFetch()	/api/v1/workspace/projection/{dept}	/api/v1/workspace/*	BFF	✅ WIRED
apiFetch()	/api/v1/workspace/entities	/api/v1/workspace/*	BFF	✅ WIRED
apiFetch()	/api/v1/workspace/metadata	/api/v1/workspace/*	BFF	✅ WIRED
apiFetch()	/api/v1/workspace/csm/*	/api/v1/workspace/*	BFF	✅ WIRED
apiFetch()	/api/v1/workspace/domain/*	/api/v1/workspace/*	BFF	✅ WIRED
apiFetch()	/api/v1/pipeline/entities	/api/v1/pipeline	PIPELINE	✅ WIRED
apiFetch()	/api/v1/pipeline/spine/*	/api/v1/pipeline	PIPELINE	✅ WIRED
apiFetch()	/api/v1/pipeline/ingest/csv	/api/v1/pipeline	PIPELINE	✅ WIRED
apiFetch()	/api/v1/pipeline/sync-checkpoints	/api/v1/pipeline	PIPELINE	✅ WIRED
apiFetch()	/api/v1/pipeline/quarantine	/api/v1/pipeline	PIPELINE	✅ WIRED
apiFetch()	/api/v1/pipeline/schema-registry	/api/v1/pipeline	PIPELINE	✅ WIRED
apiFetch()	/api/v1/intelligence/signals	/api/v1/intelligence	INTELLIGENCE	✅ WIRED
apiFetch()	/api/v1/knowledge/memories	/api/v1/knowledge	KNOWLEDGE	✅ WIRED
apiFetch()	/api/v1/knowledge/continuity-objects	/api/v1/knowledge	KNOWLEDGE	✅ WIRED
apiFetch()	/api/v1/governance/proposals	/api/v1/cognitive/govern	INTELLIGENCE	✅ WIRED
apiFetch()	/api/v1/connectors	/api/v1/connectors	CONNECTOR	✅ WIRED
apiFetch()	/api/v1/integrations/*	(in-gateway handler)	Gateway internal	✅ WIRED
apiFetch()	/api/v1/billing/subscription	/api/v1/billing	INTERNAL_BILLING	✅ WIRED
apiFetch()	/api/v1/billing/entitlements/*	/api/v1/billing	INTERNAL_BILLING	✅ WIRED
apiFetch()	/api/v1/subscriptions	(in-gateway handler)	Gateway internal	✅ WIRED
apiFetch()	/api/v1/spine-network/*	/api/v1/spine-network	MCP_CONNECTOR	✅ WIRED
apiFetch()	/api/v1/marketplace/installations/*	/api/v1/marketplace/installations	MARKETPLACE_INSTALLATION	✅ WIRED
apiFetch()	/api/marketplace/activate	(Next.js API route)	Frontend internal	⚠️ LOCAL
AuthManager	/api/v1/auth/login	/api/v1/auth	INTERNAL_AUTH	✅ WIRED
AuthManager	/api/v1/auth/signup	/api/v1/auth	INTERNAL_AUTH	✅ WIRED
AuthManager	/oauth/token	/oauth	INTERNAL_AUTH	✅ WIRED
BillingClient	/api/v1/billing/*	/api/v1/billing	INTERNAL_BILLING	✅ WIRED
SSEClient	/ws, /sse, /stream	/ws, /sse, /stream	BFF	✅ WIRED

2.2 Frontend → Gateway: GAPS

Gap	Detail	Severity
No /api/v1/workspace/discovery in ROUTES table	Handled by special-case if at line 2314, NOT in the ROUTES array	⚠️ Architectural — works but inconsistent
/api/marketplace/activate	Next.js API route, not gateway-routed	⚠️ Local only, not production-ready
Two API base URLs	NEXT_PUBLIC_IW_API_URL vs NEXT_PUBLIC_API_BASE_URL — different clients use different bases	⚠️ Configuration drift risk
Direct Spabase URL	NEXT_PUBLIC_SPINE_URL still referenced in spine client	❌ Legacy — should be removed
Descope fallback	NEXT_PUBLIC_DESCOPE_PROJECT_ID still active alongside Clerk	⚠️ Dual auth path (D11)

---

3. Gateway → Service Routing (Complete)

3.1 ROUTES Table (51 entries)

Route Prefix	Target Binding	Worker Name	D1/KV Direct Access	Status
/api/v1/auth	INTERNAL_AUTH	(in-gateway)	—	✅
/api/v1/projections	INTERNAL_PROJECTIONS	(in-gateway)	—	✅
/api/v1/capabilities/status	INTERNAL_CAPABILITY_STATUS	(in-gateway)	—	✅
/api/v1/billing	INTERNAL_BILLING	(in-gateway)	—	✅
/api/v1/tenants	INTERNAL_TENANTS	(in-gateway)	—	✅
/api/v1/support	INTERNAL_SUPPORT	(in-gateway)	—	✅
/api/v1/analytics	BFF	integratewise-workflow	D1 (analytics)	✅
/api/v1/agents	INTELLIGENCE	integratewise-intelligence	D1 + Neon	✅
/api/v1/workspace	BFF	integratewise-workflow	D1 (spine-cache)	✅
/api/v1/spine-network	MCP_CONNECTOR	integratewise-mcp-connector	D1 + Neon	✅
/api/v1/connectors	CONNECTOR	integratewise-connector	D1	✅
/api/v1/connector	CONNECTOR	integratewise-connector	D1	✅
/api/v1/loader	CONNECTOR	integratewise-connector	D1	✅
/api/v1/pipeline	PIPELINE	integratewise-pipeline	D1 + KV + Queues	✅
/api/v1/spine	SPINE	integratewise-spine	D1 + Neon	✅
/api/v1/mcp-pool	MCP_POOL	integratewise-mcp-pool	—	✅
/api/v1/intelligence	INTELLIGENCE	integratewise-intelligence	D1 + Neon	✅
/api/v1/cognitive/spine	PIPELINE	integratewise-pipeline	D1	✅
/api/v1/cognitive/entity360	PIPELINE	integratewise-pipeline	D1	✅
/api/v1/entity360	PIPELINE	integratewise-pipeline	D1	✅
/api/v1/identity	PIPELINE	integratewise-pipeline	D1	✅
/api/v1/cognitive/evidence	BFF	integratewise-workflow	D1	✅
/api/v1/cognitive/memories	KNOWLEDGE	integratewise-knowledge	D1 + R2 + Vectorize	✅
/api/v1/cognitive/signals	INTELLIGENCE	integratewise-intelligence	D1	✅
/api/v1/cognitive/think	INTELLIGENCE	integratewise-intelligence	D1 + Neon	✅
/api/v1/cognitive/act	INTELLIGENCE	integratewise-intelligence	D1 + Neon	✅
/api/v1/cognitive/govern	INTELLIGENCE	integratewise-intelligence	D1 + Neon	✅
/api/v1/cognitive/context-to-truth	INTELLIGENCE	integratewise-intelligence	D1 + Neon	✅
/api/v1/cognitive/hitl	BFF	integratewise-workflow	D1	✅
/api/v1/brainstorm	INTELLIGENCE	integratewise-intelligence	D1	✅
/api/v1/knowledge	KNOWLEDGE	integratewise-knowledge	D1 + R2 + Vectorize	✅
/api/v1/cognitive/twin	AGENT_RUNTIME	iw-agent-runtime	Durable Objects	✅
/api/v1/cognitive/brain	AGENT_RUNTIME	iw-agent-runtime	Durable Objects	✅
/api/v1/execution-packages	AGENT_RUNTIME	iw-agent-runtime	Durable Objects	✅
/api/v1/cognitive/insights	INTELLIGENCE	integratewise-intelligence	D1	✅
/api/v1/cognitive/audit	BFF	integratewise-workflow	D1	✅
/api/v1/cognitive/agents	INTELLIGENCE	integratewise-intelligence	D1	✅
/api/v1/cognitive/memory	KNOWLEDGE	integratewise-knowledge	D1	✅
/api/v1/cognitive/truth	KNOWLEDGE	integratewise-knowledge	D1 + Neon	✅
/api/v1/cognitive/projects	KNOWLEDGE	integratewise-knowledge	D1	✅
/api/v1/cognitive/status	KNOWLEDGE	integratewise-knowledge	D1	✅
/ws, /sse, /stream	BFF	integratewise-workflow	—	✅
/admin	INTERNAL_ADMIN	(in-gateway)	—	✅
/oauth	INTERNAL_AUTH	(in-gateway)	—	✅
/webhooks/slack-workflow	WEBHOOK_INGRESS	integratewise-webhook-ingress	—	✅
/webhooks/slack/interactivity	WEBHOOK_INGRESS	integratewise-webhook-ingress	—	✅
/webhooks/billing	INTERNAL_BILLING	(in-gateway)	—	✅
/webhooks	WEBHOOK_INGRESS	integratewise-webhook-ingress	—	✅
/api	HUB_CONTROLLER	hub-controller-api	D1	⚠️ UNAUTHENTICATED

3.2 Gateway → Service: GAPS

Gap	Detail	Severity
/api catch-all to HUB_CONTROLLER	Unauthenticated entry point (S1)	❌ SECURITY
/api/v1/spine not in CORE_SERVICES	Spine is bound but not in release path	❌ DEPLOYMENT
15 dangling bindings	Service names don't match wrangler name =	❌ BROKEN
5 test/prod binding leaks	HUB_CONTROLLER and MCP_POOL share targets	❌ ISOLATION
hermes unreachable	Stage 11 of runtime sequence, zero inbound bindings	❌ ARCHITECTURE
marketplace-installation zero inbound	New service, binding added but not in ROUTES	⚠️ WIRED VIA SPECIAL CASE

---

4. Service → Store Mapping (Operational D1 vs Canonical Neon)

4.1 Store Inventory

Store	Technology	Purpose	Owner
Operational Spine	D1 (integratewise-spine-staging/prod)	Connections, connectors, sync jobs, webhooks, schemas, capabilities, timeline	Spine service
Spine Cache	D1 (integratewise-spine-cache)	Shared operational cache across all services	Multiple services
Canonical Spine	Neon (FORTRESS_DATABASE_URL)	Canonical entities, relationships, lineage, promotion, audit	Pipeline (sole writer)
Analytics	D1 (integratewise-analytics)	Conversion events, performance metrics, daily aggregates	Workflow
Knowledge	D1 + R2 + Vectorize	Document chunks, embeddings, memories, search	Knowledge
Intelligence	D1 + Neon + Supabase REST	Governance policies, actions, signals, agent decisions	Intelligence
Agent Runtime	Durable Objects	Twin conversations, agent working memory	iw-agent-runtime
Sessions	KV (SESSIONS)	User sessions	Gateway
Rate Limits	KV (RATE_LIMITS)	API rate limiting	Gateway
Connector Status	KV (CONNECTOR_STATUS)	Connector health	Gateway
OAUTH State	KV (OAUTH_STATE_KV)	OAuth flow state	Gateway

4.2 Service → Store: COMPLETE MAP

SPINE (Operational + Canonical reads)

Store	Table	R/W	Status
D1 (Operational)	connections, connectors, sync-jobs, webhooks, schemas, capabilities, timeline-events	R/W	✅
Neon (Canonical)	product.workbench_overview, product.workbench_definitions	R	✅
Neon	spine.activities	R/W	✅
Neon	spine.current_entities	R	✅
Neon	knowledge.documents	R	✅ (cross-schema)
Neon	continuity.memories	R	✅ (cross-schema)
Neon	spine_connector_catalog	R	⚠️ placeholder
Neon	spine_connector_installations	R	⚠️ placeholder
Neon	governance_proposals	R	⚠️ placeholder
Neon	marketplace_packages	R	⚠️ placeholder
Neon	marketplace_installations	R	⚠️ placeholder

PIPELINE (Canonical writer)

Store	Table	R/W	Status
D1 (CANONICAL_SPINE_DB)	spine_entities, spine_timeline, spine_relationships	R/W	❌ PLACEHOLDER DB ID
D1 (CACHE_DB)	entity_cache, signal_cache, cross_data, decide_data, governance_data, merge_candidates, entity_signatures, agent_memory, signals, approval_queue, audit_log, spine_schema_registry, spine_vault, entities	R/W	❌ NO DB BINDING
Neon	entities, entity_merges, normalization_errors	R	✅ (via Supabase REST)
KV	entity:{tid}:{source}:{id}, agent:memory:*	R/W	✅
Queue	pipeline-process, knowledge-ingest, accelerator-trigger, intelligence-events, ops-dlq, signals, memory-promote	Produce/Consume	✅

KNOWLEDGE

Store	Table	R/W	Status
D1	document_chunks, search_history, consolidated_memories, embeddings, ai_sessions, ai_session_memories, ai_conversations, ai_messages, ai_memories, org_memory, personal_memory, conversational_memory, triage_results, tenant_spine_config	R/W	✅
R2	file blobs	R/W	✅
Vectorize	vector index	R/W	✅
Queue	knowledge-ingest, memory-consolidation-tasks	Consume/Produce	✅
DO	MemoryConsolidator	R/W	✅

INTELLIGENCE

Store	Table	R/W	Status
D1	cross_data, governance_data, continuity_loop, agent_decisions, audit_logs, dlq_entries, conversational_memory, personal_memory, signal_rules, situations, action_proposals, decision_memory, decision_patterns, source_reliability, trust_scores, autonomy_overrides, ai_session_memories, document_chunks, ai_sessions, session_entity_links, evidence_refs, signals, spine_metrics, events, artifact_links, emails, drive_files, brainstorm_sessions, brainstorm_insights	R/W	✅
Neon	governance_policies, actions	R/W	✅
Supabase REST	tenant_spine_config, audit_log, ai_config, decision_memory, rule_effectiveness, drift_events	R/W	✅
R2	memory content	R/W	✅
Vectorize	semantic index	R/W	✅
Queue	pipeline-process, intelligence-act, ops-dlq, signals, memory-promote	Produce/Consume	✅
DO	HandoffTimeoutDO, TriageWorkflow, BulkCleanupSwarm	R/W	✅

MCP-CONNECTOR

Store	Table	R/W	Status
D1	users, tenant_spine_config, agent_registry, connector_catalog, context_boundaries, context_exchange_log, active_work_context, agent_communication_log, handoff_packages, handoff_state_log, proposals, oauth_refresh_tokens, oauth_clients, spine_entities, signals, kb_artifacts, kb_topic_policies, spine_events, ai_sessions, ai_session_memories, session_entity_links	R/W	✅
KV	MCP_IDEMPOTENCY	R/W	✅
Queue	knowledge-ingest, pipeline-process	Produce	✅
Neon	auth/v1/jwks	R	✅

---

5. THE CRITICAL GAP: Operational → Canonical Tunnel

5.1 What's Wired

Frontend → Gateway → Pipeline → D1 (Operational) → ✅ WIRED
Frontend → Gateway → Spine → D1 (Operational) → ✅ WIRED
Frontend → Gateway → Spine → Neon (Canonical reads) → ✅ WIRED
Frontend → Gateway → Knowledge → D1 + R2 + Vectorize → ✅ WIRED
Frontend → Gateway → Intelligence → D1 + Neon → ✅ WIRED

5.2 What's BROKEN

Pipeline → CANONICAL_SPINE_DB (Neon) → ❌ PLACEHOLDER DB ID
Pipeline → D1 (entity_cache, etc.) → ❌ NO DB BINDING
Gateway → 15 dangling service bindings → ❌ BROKEN
Gateway → hermes (stage 11) → ❌ UNREACHABLE
Gateway → /api (HUB_CONTROLLER) → ❌ UNAUTHENTICATED

5.3 The Canonical Write Path (S0)

INTENDED:
Pipeline promotion → CANONICAL_SPINE_DB (Neon) → canonical entities
                    ↓
              Transactional outbox
                    ↓
              Async projections → Brain, Search, Vector, Workbench

ACTUAL:
Pipeline promotion → CANONICAL_SPINE_DB → ❌ PLACEHOLDER DB ID
                    ↓
              console.warn (silent failure)
                    ↓
              return { success: true } → ❌ LIES TO CALLER

This is S0. The highest-value single change in the entire system.

---

6. Unmapped Paths (Frontend calls that have no backend)

Frontend Call	Gateway Route	Backend	Status
/api/v1/workspace/connectors	→ BFF (workflow)	Workflow reads D1	✅ But workflow not in CORE_SERVICES
/api/v1/workspace/projection/{dept}	→ BFF	Workflow reads D1	✅ But projection logic unclear
/api/v1/workspace/entities	→ BFF	Workflow reads D1	✅ But entity source unclear
/api/v1/workspace/metadata	→ BFF	Workflow reads D1	✅ But metadata freshness unclear
/api/v1/governance/proposals	→ INTELLIGENCE	Intelligence reads D1 + Neon	✅ But governance gate not proven
/api/v1/spine-network/*	→ MCP_CONNECTOR	MCP Connector reads D1 + Neon	✅ 19 tools implemented
/api/v1/marketplace/installations/*	→ MARKETPLACE_INSTALLATION	New service, D1	✅ But binding not in ROUTES
/api/marketplace/activate	→ Next.js API route	Frontend local	⚠️ Not production

---

7. Unwired Paths (Backend exists but frontend doesn't call)

Backend Endpoint	Service	Purpose	Status
/api/v1/cognitive/think	INTELLIGENCE	Twin reasoning	❌ No frontend consumer
/api/v1/cognitive/act	INTELLIGENCE	Action execution	❌ No frontend consumer
/api/v1/cognitive/govern	INTELLIGENCE	Governance decisions	❌ No frontend consumer
/api/v1/cognitive/twin	AGENT_RUNTIME	Twin runtime	❌ No frontend consumer
/api/v1/cognitive/brain	AGENT_RUNTIME	Brain reasoning	❌ No frontend consumer
/api/v1/brainstorm	INTELLIGENCE	Brainstorm sessions	❌ No frontend consumer
/api/v1/cognitive/insights	INTELLIGENCE	AI insights	❌ No frontend consumer
/api/v1/cognitive/agents	INTELLIGENCE	Agent management	❌ No frontend consumer
/api/v1/execution-packages	AGENT_RUNTIME	Execution packages	❌ No frontend consumer
/api/v1/mcp-pool	MCP_POOL	Capability routing	❌ No frontend consumer
/api/v1/spine/*	SPINE	Spine CRUD	⚠️ Only via spineClient adapter

---

8. Priority Fix Order

#	Fix	Impact	Effort
1	S0: Make canonical write hard-fail	Silent data loss → visible error	Small
2	Wire CANONICAL_SPINE_DB to real Neon	Canonical writes actually persist	Medium
3	Add DB binding to Pipeline wrangler.toml	14 D1 tables become accessible	Small
4	Repair 15 dangling bindings	Services become reachable	Small
5	Close HUB_CONTROLLER bypass	Security hole closed	Small
6	Wire hermes or formally retire it	Stage 11 of runtime sequence	Decision needed
7	Add spine to CORE_SERVICES	Spine included in release path	Small
8	Frontend: consume workspace/discovery	First canonical read proven	Medium
9	Frontend: wire think/act/govern	Twin and governance become usable	Large
10	Remove Descope fallback	Single auth path	Small

---

Generated from: Three parallel deep audits (frontend, gateway, stores)
Files produced: apps/web/FRONTEND_DATA_FETCH_MAP.md, docs/STORE_ACCESS_MAP.md, this document