{"slug":"platform/platform-map","title":"IntegrateWise Platform Map","section":"platform","sectionLabel":"Platform","status":"unclassified","type":"document","path":"platform/platform-map.mdx","bytes":15837,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> Navigation document for v0 go-live.  \n> It maps every frontend surface to the backend services, storage ownership, and the golden execution flow.  \n> When this file and [`AGENTS.md`](../AGENTS.md) or the frozen architecture docs disagree, the frozen docs win.\n\n---\n\n```text\n                           USERS / HOSTS / AGENTS\n                                     |\n                                     |\n                              ┌─────────────┐\n                              │  One Auth   │\n                              │  Identity   │\n                              └──────┬──────┘\n                                     |\n              ┌──────────────────────┴──────────────────────┐\n              │                                             │\n              ▼                                             ▼\n    ┌──────────────────┐                         ┌──────────────────┐\n    │ Human Entry      │                         │ MCP Entry        │\n    │ Workbench        │                         │ MCP Clients      │\n    └────────┬─────────┘                         └────────┬─────────┘\n             │                                            │\n             ▼                                            ▼\n```\n\n---\n\n## Frontend Layer\n\n| App               | Surface                         | Responsibility                                                           | Vercel Project             | Custom Domain                 | Status                |\n| ----------------- | ------------------------------- | ------------------------------------------------------------------------ | -------------------------- | ----------------------------- | --------------------- |\n| `apps/web`        | Main Workbench + Tenant Routing | Primary user workbench, subdomain-based tenant routing, role-aware views | `integratewise-web`        | `app.spineworkspace.com`      | deployed, verified    |\n| `apps/platform`   | Platform Console                | Platform Control Board, Integration Manager, Governance, Continuity      | `integratewise-platform`   | `platform.spineworkspace.com` | deployed, verified    |\n| `apps/one-access` | Auth Experience                 | Login, signup, onboarding, host detection                                | `integratewise-one-access` | `auth.spineworkspace.com`     | deployed, verified    |\n| `apps/marketing`  | Public Website                  | Public marketing site                                                    | `integratewise-marketing`  | `www.spineworkspace.com`      | deployed, DNS pending |\n\nNotes:\n\n- These are **independent Next.js apps**. Each is deployed as its own Vercel project.\n- Do **not** deploy the repository root as a single Vercel Services monolith for v0; that path has already failed (`integratewise-live` build UNKNOWN). Backend services stay on Cloudflare Workers.\n\n---\n\n## Subdomain Routing\n\nv0 uses **subdomain-based routing** rather than path-based routing. Each frontend app owns a dedicated subdomain.\n\n### Domain Tiers\n\n| Domain                                  | Purpose                                      | Services                              |\n| --------------------------------------- | -------------------------------------------- | ------------------------------------- |\n| `spineworkspace.com`                    | **Production** — all workers, MCP, frontends | Gateway, all services, all apps       |\n| `integratewise.online`                  | **Development** — workers, MCP, spine        | Gateway, services, dev apps           |\n| `integratewise.ai` / `integratewise.co` | **Customer Zero** — workers, MCP, spine      | Gateway, services, customer-zero apps |\n\n### Production Subdomains (`spineworkspace.com`)\n\n| Subdomain                     | App / Surface     | Project                    | Backend origin                                  |\n| ----------------------------- | ----------------- | -------------------------- | ----------------------------------------------- |\n| `www.spineworkspace.com`      | Public website    | `integratewise-marketing`  | `NEXT_PUBLIC_API_BASE_URL` (Cloudflare Gateway) |\n| `app.spineworkspace.com`      | Main Workbench    | `integratewise-web`        | Cloudflare Gateway                              |\n| `platform.spineworkspace.com` | Platform Console  | `integratewise-platform`   | Cloudflare Gateway                              |\n| `auth.spineworkspace.com`     | Auth / onboarding | `integratewise-one-access` | Cloudflare Gateway                              |\n| `{tenant}.spineworkspace.com` | Tenant workspace  | `integratewise-web`        | Cloudflare Gateway                              |\n| `gateway.spineworkspace.com`  | API Gateway       | Cloudflare Worker          | Direct                                          |\n\n### Customer Zero Subdomains (`integratewise.ai`)\n\n| Subdomain                  | App / Surface       |\n| -------------------------- | ------------------- |\n| `app.integratewise.ai`     | Main Workbench      |\n| `gateway.integratewise.ai` | API Gateway         |\n| `preview.integratewise.ai` | Preview deployments |\n\n### Development Subdomains (`integratewise.online`)\n\n| Subdomain                       | App / Surface          |\n| ------------------------------- | ---------------------- |\n| `app.integratewise.online`      | Main Workbench (dev)   |\n| `platform.integratewise.online` | Platform Console (dev) |\n\nPath-based rewrites in the repository root `vercel.json` are **not** used for v0. The root `vercel.json` Services manifest is archived until backend services are moved onto Vercel (not planned for v0).\n\n### DNS setup (required)\n\n`spineworkspace.com` is on Cloudflare nameservers and is already added to the Vercel team.\nFor each custom domain, add a **CNAME record** in Cloudflare DNS pointing to `cname.vercel-dns.com`:\n\n```text\nwww.spineworkspace.com       CNAME  cname.vercel-dns.com.    (proxied)\napp.spineworkspace.com       CNAME  cname.vercel-dns.com.    (proxied)\nplatform.spineworkspace.com  CNAME  cname.vercel-dns.com.    (proxied)\nauth.spineworkspace.com      CNAME  cname.vercel-dns.com.    (proxied)\n```\n\nFor tenant subdomains (`{tenant}.spineworkspace.com`), add a **wildcard CNAME**:\n\n```text\n*.spineworkspace.com         CNAME  cname.vercel-dns.com.    (proxied)\n```\n\nVercel TXT verification record for `www.spineworkspace.com`:\n\n```text\n_vercel.spineworkspace.com   TXT    vc-domain-verify=www.spineworkspace.com,39dcfb1d9a7120c3ebf7\n```\n\n---\n\n## Platform Gateway\n\n**Path:** `services/gateway`\n\nResponsibilities:\n\n- Authentication validation\n- Tenant resolution\n- Workspace resolution\n- Request routing\n- Rate limits\n- Zero-trust enforcement\n\nThe Gateway is the single frontend↔backend entrypoint, deployed as a Cloudflare Worker.\n\n```text\n         │\n         ├─────────────────────────────────────────────────┐\n         │                                                 │\n         ▼                                                 ▼\n```\n\n---\n\n## Core Platform Services\n\n### Tenant & Identity\n\n#### `services/tenants`\n\nOwns:\n\n- tenant lifecycle\n- provisioning\n- runtime registry\n\nStorage:\n\n- **Neon Control Plane**\n  - `tenants`\n  - `deployment_manifests`\n  - `tenant_runtime_registry`\n\n#### `services/admin`\n\nOwns:\n\n- platform administration\n- policies\n- operations\n\n#### `services/identity`\n\nOwns:\n\n- users\n- memberships\n- roles\n- permissions\n\nStorage:\n\n- **D1 Tenant Spine**\n\n---\n\n### Connectivity Fabric\n\n#### `services/integration-management-mcp`\n\nOwns:\n\n- connector discovery\n- MCP integration management\n- tool registration\n\n#### `services/provider-management-mcp`\n\nOwns:\n\n- provider metadata\n- provider capabilities\n\n#### `services/connector-sync`\n\nOwns:\n\n- OAuth sync\n- ingestion jobs\n- connector hydration\n\n#### `services/mcp-connector`\n\nOwns:\n\n- MCP connector runtime\n\n#### `services/mcp-pool`\n\nOwns:\n\n- MCP tool execution pool\n\nStorage:\n\n- **Neon**\n  - `connector_catalog`\n  - `mcp_catalog`\n- **D1**\n  - `tenant_connections`\n  - `capability_registry`\n\n---\n\n### Spine / Context Layer\n\n#### `services/spine`\n\nThe operational truth layer.\n\nOwns:\n\n- entities\n- relationships\n- versions\n- lineage\n\nStorage:\n\n- **D1**\n  - `entity_spine`\n  - `external_identities`\n  - `spine_relationships`\n  - `entity_versions`\n\n```text\n              │\n              │\n              ▼\n```\n\n#### `services/loader`\n\nOwns:\n\n- ingestion pipeline\n- normalization\n- hydration\n\n#### `services/knowledge`\n\nOwns:\n\n- documents\n- RAG\n- embeddings\n\nStorage:\n\n- D1\n- R2\n- Vectorize\n\n---\n\n### Intelligence Layer\n\n#### `services/hermes`\n\nOwns:\n\n- assistant experience\n- interaction layer\n\n#### `services/twin-orchestrator`\n\nOwns:\n\n- Twin planning\n- cognitive orchestration\n\n#### `services/iw-agent-runtime`\n\nOwns:\n\n- agent execution\n- tools\n- memory interaction\n\n#### `services/continuity`\n\nOwns:\n\n- agent state\n- continuity ledger\n- session memory\n\nStorage:\n\n- **D1**\n  - `memory_entries`\n  - `continuity_ledger`\n  - `agent_sessions`\n\n---\n\n## Execution & Governance\n\n#### `services/task-management`\n\nOwns:\n\n- tasks\n- work items\n- assignments\n\n#### `services/workflow`\n\nOwns:\n\n- long-running workflows\n\n#### `services/pipeline`\n\nOwns:\n\n- business pipelines\n\n#### `services/intelligence`\n\nOwns:\n\n- reasoning services\n- AI capabilities\n\nExecution Flow:\n\n```text\nUser Intent\n    │\n    ▼\nTwin Orchestrator\n    │\n    ▼\nCapability Service\n    │\n    ▼\nGovernance\n    │\n    ▼\nTask / Workflow\n    │\n    ▼\nProvider Execution\n    │\n    ▼\nReconciliation\n```\n\n---\n\n## Event + Realtime Infrastructure\n\nCloudflare Runtime:\n\n```text\nWorkers\n  │\n  ├─ Gateway\n  └─ Services\n\nD1\n  │\n  └─ Operational Spine\n\nKV\n  │\n  ├─ Sessions\n  └─ Cache\n\nR2\n  │\n  ├─ Evidence\n  └─ Documents\n\nQueues\n  │\n  ├─ Sync jobs\n  ├─ Hydration\n  └─ Execution retry\n\nDurable Objects\n  │\n  ├─ realtime sessions\n  └─ coordination\n\nWorkers AI\n  │\n  └─ inference\n\nAI Gateway\n  │\n  └─ model routing\n```\n\n---\n\n## Data Authority\n\n### JSONB Canvas Views\n\nCanvas views (workspace pages) are stored as **JSONB in D1/PostgreSQL**, not localStorage.\n\n| Store                     | What it holds                                          | Location                             |\n| ------------------------- | ------------------------------------------------------ | ------------------------------------ |\n| `workspace_page` entities | Canvas component state, layout, data bindings, actions | D1 `entity_spine.attributes` (JSONB) |\n| `tenant_view_registry`    | View contracts, fetch plans, field projections         | D1 `tenant_view_registry` (JSONB)    |\n| `tenant_view_links`       | Cross-view navigation contracts                        | D1 `tenant_view_links` (JSONB)       |\n| `memory_entries`          | Agent/operational memory                               | D1 `memory_entries` (JSONB)          |\n| `context_fetch_runs`      | Fetch traces, SQL traces, cache traces                 | D1 `context_fetch_runs` (JSONB)      |\n\nThe canvas view JSONB structure:\n\n```json\n{\n  \"icon\": \"📊\",\n  \"department\": \"sales\",\n  \"components\": [\n    {\n      \"id\": \"c1\",\n      \"type\": \"kanban\",\n      \"label\": \"Pipeline\",\n      \"x\": 0,\n      \"y\": 2,\n      \"width\": 8,\n      \"height\": 6,\n      \"dataSource\": { \"type\": \"spine\", \"sourceId\": \"sales.opportunities\" },\n      \"actions\": [{ \"id\": \"advance\", \"label\": \"Advance\", \"capability\": \"deal.advance\" }],\n      \"config\": { \"groupBy\": \"stage\" }\n    }\n  ],\n  \"isFavorite\": false,\n  \"isTemplate\": true,\n  \"sortOrder\": 0\n}\n```\n\n### Neon Control Plane\n\nOwns:\n\n- **Tenant**\n  - `tenants`\n  - `organizations`\n  - `subscriptions`\n  - `entitlements`\n- **Marketplace**\n  - `connector_catalog`\n  - `plugin_catalog`\n  - `mcp_catalog`\n- **Governance**\n  - `platform_policies`\n  - `schema_versions`\n\n```text\n                 │\n                 │\n                 ▼\n```\n\n### D1 Tenant Operational Spine\n\nOwns:\n\n- workspace state\n- entity graph\n- memory\n- continuity\n- approvals\n- work items\n- projections\n- reconciliation\n\n---\n\n## Golden Flow\n\n### CONNECT\n\n```text\nConnector Marketplace\n        │\n        ▼\nIntegration Service\n        │\n        ▼\nConnector Sync\n        │\n        ▼\nLoader\n        │\n        ▼\nSpine\n```\n\n### UNDERSTAND\n\n```text\nSpine\n        │\n        ▼\nKnowledge\n        │\n        ▼\nBusiness Context\n        │\n        ▼\nTwin\n```\n\n### ACT\n\n```text\nTwin Proposal\n        │\n        ▼\nGovernance\n        │\n        ▼\nCapability\n        │\n        ▼\nExecution\n```\n\n### VERIFY\n\n```text\nProvider\n        │\n        ▼\nReconciliation\n        │\n        ▼\nEvidence\n        │\n        ▼\nProjection Refresh\n```\n\n---\n\n## Request Path Through the Stack\n\n```text\nBrowser / MCP Client\n        │\n        ▼\nFrontend (Vercel)\n        │\n        ├─ NEXT_PUBLIC_* inlined at build time\n        └─ API routes → Gateway\n        │\n        ▼\nGateway (Cloudflare Worker)\n        │\n        ├─ validate auth\n        ├─ resolve tenant/workspace\n        └─ route to service\n        │\n        ▼\nService (Cloudflare Worker)\n        │\n        ├─ read from Spine/D1/KV/R2\n        ├─ emit write intent\n        └─ return projection\n        │\n        ▼\nSpine / Storage (D1, R2, KV, Vectorize)\n```\n\n---\n\n## Deployment Boundaries\n\n| Plane               | Ownership                                                        | Deploy Target                      | DB Infrastructure                             |\n| ------------------- | ---------------------------------------------------------------- | ---------------------------------- | --------------------------------------------- |\n| Frontend experience | `apps/web`, `apps/platform`, `apps/one-access`, `apps/marketing` | Vercel (one project per app)       | **None** — reads via Projection API only      |\n| Gateway             | `services/gateway`                                               | Cloudflare Worker                  | D1 (Operational Spine cache)                  |\n| Core services       | `services/*`                                                     | Cloudflare Workers                 | D1 + KV + R2 + Vectorize + Durable Objects    |\n| Operational truth   | `services/spine` + D1                                            | Cloudflare D1                      | D1 (cache), reads from Neon via sync pipeline |\n| Control plane       | Tenant/provider/catalog data                                     | Neon                               | PostgreSQL (Canonical DB — Fortress)          |\n| Files / evidence    | Knowledge, loader outputs                                        | Cloudflare R2                      | R2 object storage                             |\n| Model routing       | AI calls                                                         | Cloudflare AI Gateway + Workers AI | AI Gateway routing                            |\n\n**The rule:** Vercel frontend NEVER touches a database directly. All reads go through the Gateway → Projection Platform → Operational Spine (D1/KV). All writes go through the Promotion Queue → Canonical DB (Neon).\n\n---\n\n## Architectural Law\n\n- **Frontend owns experience.**\n- **Gateway owns access.**\n- **Services own business capability.**\n- **Spine owns operational truth.**\n- **Projection owns views.**\n- **AI proposes.**\n- **Governance controls.**\n- **Reconciliation confirms.**\n"}