{"slug":"architecture/DEPLOYMENT_PREREQUISITES","title":"IntegrateWise / Spine Workspace — Deployment Prerequisites","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/DEPLOYMENT_PREREQUISITES.mdx","bytes":21220,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** Release prerequisite — subordinate to canonical architecture\n**Date:** 2026-08-20\n**Purpose:** Define the mandatory infrastructure, contract, and proof gates that must exist before any deployment event\n\nThe deployment prerequisites are now clear from the repository audits and attached release material. The mistake to avoid is treating deployment as \"deploy Workers + deploy frontend.\" Before that, the **shared platform contract, credentials, routing, storage, connector, MCP, projection, and governance paths must all exist and be isolated by environment**.\n\n---\n\n## 0. Environment model must be frozen first\n\nThere are three distinct infrastructure classes:\n\n```text\nA. Product Engineering\n   development\n   CI\n   staging\n   test tenants\n\nB. Customer Zero\n   IntegrateWise operational tenant\n   production-grade but isolated\n\nC. Customer Production\n   external tenant runtimes\n   isolated from A and B\n```\n\nDevelopment infrastructure may use fixed engineering choices. Customer-facing projections must not force customers to choose or understand underlying infrastructure providers. The Platform resolves those behind the connector/capability abstraction.\n\n**Prerequisite:** no D1, KV, R2, queue, vector, credential, tenant, or service binding may accidentally be shared across these partitions.\n\n---\n\n## 1. Shared Cloudflare Platform foundation\n\nBefore any frontend testing event, the Platform must be reachable.\n\nRequired:\n\n```text\nCloudflare account\nCloudflare Workers environments\nWorkers for Platforms / tenant routing where applicable\nGateway\nPipeline\nConnector runtime\nMCP Connector / Spine Network MCP\nKnowledge\nContinuity\nIntelligence\nWorkflow\nHermes / Execution\nReconciliation\n```\n\nDo **not** deploy every Worker in the repository simply because it has a `wrangler.toml`. The repository audit distinguishes the smaller core release profile from many bound, partial, or zero-inbound services.\n\nFor every production Worker:\n\n```text\nworker name\nenvironment\nroute/domain\nservice bindings\nD1 bindings\nKV bindings\nR2 bindings\nqueue producers/consumers\nDO bindings\nAI/model bindings\nsecret inventory\nhealth endpoint\nowner\nrelease version\nrollback version\n```\n\nmust be known before deployment.\n\n---\n\n## 2. DNS and ingress\n\nThe following ingress surfaces must resolve and terminate correctly before integrated testing:\n\n```text\ngateway.integratewise.ai\nauth / OneAuth endpoint\nmcp.integratewise.ai\nWorkbench / Spine Workspace domains\nplatform control surface\nmarketplace/activation routes as required\n```\n\nThe Gateway is the authoritative platform ingress. Frontends must not bypass it via arbitrary direct service rewrites.\n\nRequired validation:\n\n```text\nDNS resolves\nTLS valid\nCORS correct\nCSP correct\nauthenticated request succeeds\nunauthenticated request fails correctly\ntenant is derived server-side\ncorrelation/trace ID generated\n```\n\nThe source material specifically identifies unresolved Gateway/Auth DNS and incomplete bindings as release blockers.\n\n---\n\n## 3. OneAuth / identity / tenant authority\n\nThis is **Flow D**, and it precedes A/B/C ingestion.\n\nRequired live path:\n\n```text\nUser / Host\n   ↓\nOneAuth\n   ↓\nAuthentication\n   ↓\nOrganization resolution\n   ↓\nTenant resolution\n   ↓\nMembership / role / permission\n   ↓\nConsent\n   ↓\nWorkspace binding\n   ↓\nRuntime activation\n```\n\nBefore testing, you need:\n\n```text\nproduction/test auth provider configuration\nclient IDs\nserver secrets\nredirect URIs\nwebhook secret\nsession verification\ntenant mapping\nrole/RBAC mapping\nconsent persistence\nrevocation\nlogout/session expiry\nservice identity model\n```\n\nThe Gateway must **re-derive authority**. Browser-supplied tenant, role, entitlement, policy, connector scope, or capability grants cannot be authoritative.\n\nThe current ecosystem audit identifies default/preview tenant fallback as a key item to eliminate before release proof.\n\n---\n\n## 4. Central secret and environment configuration\n\nThis needs to exist before anything is deployed.\n\nDo not create one giant `.env` and copy it everywhere.\n\nYou need a controlled inventory:\n\n```text\nENVIRONMENT\nSERVICE\nSECRET NAME\nOWNER\nSOURCE\nROTATION POLICY\nUSED BY\nLAST VERIFIED\n```\n\nTypical groups:\n\n### Platform\n\n```text\nCLOUDFLARE_ACCOUNT_ID\ndeployment API token\nGateway service credentials\nencryption key\nadmin/service credentials\n```\n\n### Identity\n\n```text\nauth publishable/client ID\nauth server secret\nwebhook secret\nOAuth redirect configuration\n```\n\n### Connectors\n\n```text\nprovider client ID\nprovider client secret\nprovider webhook secret\nNango/configured connector runtime secret if used\n```\n\n### MCP\n\n```text\nMCP OAuth client\nMCP client credentials where applicable\nresource/audience configuration\nservice-to-service auth\ninternal MCP Pool service identity\n```\n\n### AI/model providers\n\n```text\nAI Gateway configuration\nprovider API keys\nmodel-routing policy\nlocal-model endpoint if used\n```\n\n### Frontend\n\nOnly browser-safe values:\n\n```text\nNEXT_PUBLIC_IW_API_URL\nauth publishable key\npublic application IDs\nfeature/version identifiers\n```\n\nProvider secrets, Nango secrets, MCP service secrets, model keys, encryption keys, admin secrets, and connector credentials **must not be in browser-visible environment variables**. The attached environment-variable audit already identified the need to converge frontends onto a single public Gateway URL.\n\n---\n\n## 5. Storage and migrations\n\nBefore integrated testing, all required stores must exist in the correct environment.\n\nAt minimum:\n\n```text\ncanonical / promoted Spine store\ntenant operational D1\nKV\nR2\nVector/Search\nDurable Objects\nQueues\n```\n\nAnd for every store:\n\n```text\nenvironment-specific resource\nmigration version\nbackup policy\nrestore procedure\nretention\nencryption\ntenant boundary\nservice owner\n```\n\nThere is still an architectural storage-authority discrepancy across historical material, so deployment must follow the **current repository authority**, not old resource names. A D1 database named something like `canonical-spine` is not automatically canonical authority.\n\nMost importantly:\n\n> **Do not begin Customer Zero or external testing while canonical promotion is placeholder/skipped.**\n\nThat is explicitly called out as stop-ship drift in the ecosystem audit.\n\n---\n\n## 6. Connector Marketplace control plane\n\nThis is mandatory.\n\nA connector cannot be \"some source code plus a few env vars.\"\n\nEach connector needs a machine-readable definition covering:\n\n```text\nconnector identity\nprovider\nauth method\ncredential policy\nscopes\nOAuth URLs\ncallback URL\nwebhooks\nsupported objects\nsync strategy\nentity mappings\ncapabilities\nMCP exposure if any\nADK capability mapping\ngovernance class\nruntime adapter\nhealth check\nversion\nlifecycle\n```\n\nThe connector control plane should include:\n\n```text\nConnector Catalog\nAuth Profiles\nCredential Policies\nWebhook Registry\nSync Definitions\nEntity Mapping Registry\nCapability Registry\nDeployment Manifest\nHealth / Lifecycle State\n```\n\nThis is explicitly supported in the connector architecture material.\n\n---\n\n## 7. ConnectionBinding / \"connect once\" registry\n\nThis is one of the most important prerequisites.\n\nA connected provider must be reusable by all authorized surfaces without each surface creating another OAuth relationship.\n\nRequired durable record:\n\n```text\nConnectionBinding\n├── tenant\n├── workspace\n├── principal\n├── provider\n├── provider workspace/account\n├── source kind\n│   ├── host-declared\n│   └── IW-managed\n├── opaque credential/delegation ref\n├── confirmed scopes\n├── consent\n├── policy grants\n├── capability grants\n├── primary route\n├── health\n├── freshness\n├── provenance\n├── sync state\n├── reconciliation state\n├── authorized consumers\n├── audit\n└── revocation\n```\n\nThe current audit says this is not yet sufficiently proven as a shared durable registry; in-memory fallback exists. That must be resolved before public testing.\n\n---\n\n## 8. Host connection discovery\n\nThis is separate from connector ownership.\n\nFor ChatGPT, Claude, Vercel, GitHub, etc.:\n\n```text\nHost\n  ↓\nOneAuth / MCP Auth\n  ↓\nDiscovery\n  ↓\nHost-declared capabilities / eligible connections\n  ↓\nConsent + policy\n  ↓\nConnectionBinding\n  ↓\nSpine Network\n```\n\nIntegrateWise should **not copy host tokens** just because the host already has a connection.\n\nHost connections are discovered and projected only where the host exposes an authorized delegation/capability route.\n\nFallback:\n\n```text\nNo usable host route\n    ↓\nConnector Marketplace\n    ↓\nIW-managed OAuth\n```\n\nThis distinction is already captured in the ecosystem companion.\n\n---\n\n## 9. MCP authentication and public MCP boundary\n\nBefore any AI-host testing, `mcp.integratewise.ai` needs to be production-ready.\n\nRequired:\n\n```text\nOAuth / MCP Auth\nclient identity\ntenant binding\nuser/principal binding\nscopes\nresource metadata\ntool visibility policy\nread/write classification\napproval requirements\nconnector dependencies\naudit\nrevocation\nrate limiting\n```\n\nAn MCP client does not inherit full Workbench or tenant administration access simply because it authenticated.\n\nPublic MCP must expose **semantic business capabilities**, not internal engine operations.\n\nGood:\n\n```text\nprepare_account_brief\nretrieve_verified_context\nresolve_customer_risk\ncreate_governed_followup\n```\n\nBad:\n\n```text\nraw_d1_query\npipeline_write\ngovernance_set_approved\nmemory_insert\nloader_execute_internal\n```\n\nAlso: treat the current \"19 tools\" as a **release contract**, not a permanent architecture invariant.\n\n---\n\n## 10. Internal MCP Pool / ADK\n\nSeparate from public MCP.\n\nRequired for Customer Zero/internal orchestration:\n\n```text\nMCP server registry\ntool registry\nagent registry\nmodel registry\ncapability manifests\nallowed tenant filters\nallowed user filters\nservice identity\nhealth\naudit\nrouting\n```\n\nThe current repo audit indicates MCP Pool reachability/registry state is not yet production-proven and includes process-local/configuration drift. This must be corrected before treating it as a shared runtime.\n\n---\n\n## 11. Discovery Engine\n\nBefore onboarding can feel automatic, Discovery must exist.\n\nIt needs to discover:\n\n```text\nhost capabilities\nexisting ConnectionBindings\navailable connectors\nschemas\nprovider objects\nunmapped events\ncapabilities\ndependencies\nhealth state\n```\n\nBut Discovery is **proposal-only**:\n\n```text\nDiscover\n→ classify\n→ suggest\n→ request consent / mapping\n```\n\nnot:\n\n```text\nDiscover\n→ automatically steal token\n→ automatically ingest all data\n```\n\n---\n\n## 12. Loader / Normalizer / Triage paths\n\nThese must be separated.\n\n### Flow A — structured operational\n\n```text\nCRM / ERP / system record\n→ Loader\n→ Normalizer\n→ identity resolution\n→ mapping\n→ promotion\n→ Spine\n```\n\n### Flow B — unstructured work context\n\n```text\nEmail / document / message / project artifact\n→ Loader\n→ Normalizer\n→ chunk/reference/evidence\n→ mapping\n→ promotion\n→ Spine\n```\n\n### Flow C — AI/Brainstorming continuity\n\nThe latest tested vertical proof explicitly established:\n\n```text\nauthorized AI/chat reference\n→ Brainstorming\n→ Triage\n→ compare / dedupe / consolidate\n→ novel candidate\n→ pending governance\n→ bounded context\n```\n\nFlow C does **not** go through Loader/Normalizer in the tested design.\n\nThat local integration proof passed, but it is not yet a live-provider deployment proof.\n\n---\n\n## 13. Canonical promotion path\n\nThis is a hard release prerequisite.\n\nNeed a complete verified chain:\n\n```text\nSource\n→ ingestion\n→ normalize/triage\n→ provenance\n→ promotion decision\n→ canonical writer\n→ canonical commit\n→ outbox\n→ projection invalidation\n```\n\nAtomic mutation should pair durable truth with its event/outbox record.\n\nNo:\n\n```text\nwrite data\nthen maybe publish event\n```\n\nbecause that can split state from downstream projections.\n\n---\n\n## 14. Projection Engine and frontend/backend contract map\n\nBefore testing, every important frontend surface needs a contract map.\n\nNot:\n\n```text\nUI table ↔ database table\n```\n\nInstead:\n\n```text\nWorkbench route\n   ↓\nProjection ID / version\n   ↓\nGateway endpoint\n   ↓\nProjection Service / Engine\n   ↓\ncanonical entity family + operational read model\n   ↓\nRBAC / tenant / freshness policy\n```\n\nFor actions:\n\n```text\nUI interaction\n→ capability ID\n→ schema\n→ governance class\n→ execution owner\n→ reconciliation\n```\n\nThis is the **Projection Binding Registry** that the current canonical ecosystem work says is still required.\n\n---\n\n## 15. SharedWorkbench / projection contract\n\nThe frontends should all consume the same composition authority.\n\nRequired:\n\n```text\nProjection Engine\n→ versioned SharedWorkbench / projection DTO\n→ Gateway\n→ web / mobile / desktop / host UI / Twin context\n```\n\nThe frontend needs explicit states:\n\n```text\nloading\nready\npartial\nempty\nstale\ndegraded\nunauthorized\nforbidden\nunavailable\noffline\nnot configured\n```\n\nA failed live projection must never silently become demo or seed data.\n\n---\n\n## 16. Twin readiness\n\nTwin needs to be live only after grounded context exists.\n\nPrerequisites:\n\n```text\ncontext assembly\nbounded retrieval\ncitations\nmemory scopes\nprovenance\nsignal access\ncapability access\npolicy context\napproval awareness\n```\n\nTwin may:\n\n```text\nobserve\norient\nsummarize\ndraft\nplan\nrecommend\npropose\n```\n\nTwin may not:\n\n```text\napprove itself\nwrite canonical truth directly\nclaim provider completion\nbypass governance\n```\n\n---\n\n## 17. Model and agent deployment\n\nRequired registries:\n\n```text\nModel Registry\nAgent Registry\nCapability Registry\nTool Registry\nPolicy Registry\n```\n\nModel routing requires:\n\n```text\nprovider\nmodel ID\nenvironment\nallowed purposes\ntenant policy\nfallback order\ncost controls\nrate limits\nobservability\nhealth\n```\n\nThe recent vertical proof discovered an important naming distinction:\n\n- `omni-router` currently routes connector/tool execution.\n- `model-gateway` is the model/provider routing boundary.\n\nDo not merge those responsibilities accidentally.\n\n---\n\n## 18. Capability Fabric\n\nBefore governed actions can be tested:\n\n```text\ncapability registry\ncapability version\ninput/output schema\nrequired connection\nrequired scope\nrisk class\nrequired approval\nexecution adapter\nreconciliation contract\n```\n\nResolver output should be something like:\n\n```text\nrequested intent\n→ capability\n→ eligible route\n→ policy\n→ execution plan\n```\n\nnot hardcoded provider logic in the UI.\n\n---\n\n## 19. Governance\n\nBefore any write capability is enabled:\n\n```text\nproposal\npolicy evaluation\nauthority evaluation\nhuman approval where required\nimmutable approved plan\nsigned/attributable approval\naudit\n```\n\nA user click, Twin response, workflow, MCP call, or agent does **not** execute directly.\n\n---\n\n## 20. Hermes / execution\n\nHermes must be actually reachable, not merely present as a Worker.\n\nRequired path:\n\n```text\nApproved execution plan\n→ Hermes\n→ capability route\n→ provider\n→ provider receipt\n```\n\nThe current architecture audit explicitly identifies Hermes as architecture-critical but orphaned/not adequately reachable in the core release profile.\n\nThat is a stop-ship issue for consequential actions.\n\n---\n\n## 21. Sync + reconciliation\n\nProvider acceptance is not completion.\n\nNeed:\n\n```text\nprovider receipt\n→ observe provider state\n→ compare expected vs actual\n→ reconciliation status\n→ evidence\n→ promotion\n→ projection refresh\n```\n\nThe complete loop is still one of the principal runtime proof gaps identified in the current ecosystem audit.\n\n---\n\n## 22. Audit + evidence + observability\n\nBefore Customer Zero testing:\n\n```text\nlogs\ndistributed traces\ncorrelation IDs\naudit events\nprovider receipts\nevidence references\nqueue failures\nDLQ\nretry counts\nconnector health\nprojection freshness\nMCP calls\nAI/model usage\napproval history\nreconciliation history\n```\n\nYou need dashboards and alerts for the core operational loop, not just Worker uptime.\n\n---\n\n## 23. Frontend prerequisites\n\nEach frontend can deploy independently, but all must use the same Platform contract.\n\nRequired:\n\n```text\napps/web\napps/platform / canonical operator surface\nmobile/desktop if included in test\nCustomer Zero profile\n```\n\nEvery frontend must use:\n\n```text\nauthenticated Gateway\nversioned projection contracts\nversioned capability contracts\n```\n\nand not:\n\n```text\ndirect D1\ndirect Neon\ndirect provider API\ndirect internal MCP\nfrontend-managed OAuth secrets\n```\n\n---\n\n## 24. Platform Console prerequisites\n\nBefore testing the ecosystem operationally, the Platform surface needs enough real functionality to observe and control:\n\n```text\ntenant\nconnections\nconnector health\nactivation\ncapabilities\nMCP\nmodels\nagents\nprojection manifests\nqueues\ngovernance\nexecution\nreconciliation\naudit\ndeployment\n```\n\nThe current audit states that Platform Console has the right shape but still contains mock/static fallback and incomplete control endpoints.\n\nSo it cannot yet be treated as authoritative operations control until those paths are wired.\n\n---\n\n## 25. Marketplace assets\n\nBefore marketplace submissions, publishable assets must exist:\n\n```text\nIW Spine Network MCP metadata\nPlugin manifest\nOAuth configuration\nprivacy policy\nterms\nsupport URL\ndocumentation\nsecurity description\nreviewer instructions\ndemo/test tenant\ncapability/tool descriptions\nscreenshots\nicons\nversion\nchangelog\n```\n\nConnector Marketplace remains the internal activation surface.\n\nPlugin/MCP/provider marketplaces are distribution channels.\n\nThe canonical preparation sequence explicitly places marketplace submissions **after** private certification and clean-tenant proof.\n\n---\n\n## 26. Deployment artifact freeze\n\nBefore testing, every deployed component needs one matching release version.\n\n```text\nGit SHA\nfrontend version\nGateway version\nWorker versions\nMCP version\nprojection contract version\ncapability contract version\nschema version\nmigration ledger\nconnector manifest version\nmodel/agent config version\n```\n\nDo not test a frontend from commit X against Gateway Y and migrations from Z and then call the result a release candidate.\n\n---\n\n## 27. Rollback and revocation\n\nMust exist before Customer Zero.\n\nYou need to prove:\n\n```text\nfrontend rollback\nWorker rollback\nschema/migration rollback strategy\nconnection revoke\nOAuth revoke\nMCP client revoke\nagent disable\nmodel disable\ncapability disable\ntenant suspend\nqueue pause\nbad projection rollback\nbad deployment rollback\n```\n\n---\n\n## 28. Required pre-test vertical proof\n\nBefore the broader testing event, one closed journey must work:\n\n```text\nFlow D\nidentity + tenant + consent\n\n\n        ↓\n\n\nConnection / authorized source\n\n\n        ↓\n\n\nA or B ingestion\nLoader → Normalizer\n\n\nand/or\n\n\nC ingestion\nBrainstorming → Triage\n\n\n        ↓\n\n\nSpine materialization / promotion\n\n\n        ↓\n\n\nProjection Engine\n\n\n        ↓\n\n\nWorkbench\n\n\n        ↓\n\n\nTwin context\n\n\n        ↓\n\n\nCapability\n\n\n        ↓\n\n\nGovernance\n\n\n        ↓\n\n\nHermes\n\n\n        ↓\n\n\nProvider action\n\n\n        ↓\n\n\nRe-ingest\n\n\n        ↓\n\n\nReconciliation\n\n\n        ↓\n\n\nVerified promotion\n\n\n        ↓\n\n\nWorkbench refresh\n```\n\nYou already have a deterministic local proof for the **A/B/C → bounded MCP context** part, including tenant isolation, consent, provenance, Flow C deduplication, and bounded context.\n\nWhat remains is the **live-environment continuation**:\n\n```text\nreal identity\nreal connection\nreal canonical promotion\nreal projection\nreal approval\nreal Hermes action\nreal provider reconciliation\nreal browser readback\n```\n\n---\n\n## Deployment readiness order\n\nThe sequence to follow:\n\n```text\n1. Environment isolation\n2. Secret/config source of truth\n3. DNS + Cloudflare account/runtime\n4. Identity / OneAuth / tenant authority\n5. Storage + migrations\n6. Gateway\n7. Connector catalog + credential wall\n8. Durable ConnectionBinding registry\n9. Discovery\n10. Loader / Normalizer / Triage\n11. Canonical writer + outbox\n12. Projection Binding Registry\n13. Projection Engine + frontend read path\n14. Public MCP Auth + Spine Network MCP\n15. Internal MCP Pool + ADK registries\n16. Models + agents\n17. Capability Fabric\n18. Governance\n19. Hermes\n20. Sync / reconciliation\n21. Evidence / audit / observability\n22. Platform Console operational controls\n23. Frontend deployments\n24. Customer Zero vertical test\n25. Customer Zero daily-use proof\n26. External clean-tenant test\n27. Marketplace certification\n28. Public release\n```\n\n---\n\n## The immediate blockers\n\nBased on the repository audits, the highest-priority prerequisites are not more UI or more connectors. They are:\n\n1. **Authoritative identity/tenant path**\n2. **Environment isolation and secret/config management**\n3. **Durable connect-once `ConnectionBinding` registry**\n4. **Real canonical promotion path**\n5. **Projection Binding Registry + Gateway-only reads**\n6. **Production-ready public MCP Auth**\n7. **Reachable MCP Pool / capability registries**\n8. **Reachable Hermes**\n9. **End-to-end action → reconciliation → refresh proof**\n10. **Customer Zero isolated deployment**\n\nUntil those are true, deploying more surfaces only increases the amount of unverified infrastructure.\n"}