{"slug":"business/VERCEL_PROJECT_TOPOLOGY","title":"Vercel Project Topology","section":"business","sectionLabel":"Business","status":"unclassified","type":"document","path":"business/VERCEL_PROJECT_TOPOLOGY.mdx","bytes":5215,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## Overview\n\nIntegrateWise requires two independent Vercel projects to deploy the marketing site and product web app. Each project has its own Git configuration, deployment pipeline, and domain mapping.\n\n| App               | Location         | Vercel Project                 | Root Path        | Environment                                         | Status            |\n| ----------------- | ---------------- | ------------------------------ | ---------------- | --------------------------------------------------- | ----------------- |\n| **Marketing**     | `apps/marketing` | `integratewise-live-marketing` | `apps/marketing` | `spineworkspace.com/marketing` → `integratewise.ai` | ✅ Active         |\n| **Web (Product)** | `apps/web`       | `integratewise-live-web`       | `apps/web`       | `spineworkspace.com/web` → `app.integratewise.ai`   | 🔄 Create project |\n\n## Git Deployment Status\n\nAll projects have Git auto-deployment enabled in their `vercel.json`:\n\n```json\n{\n  \"git\": {\n    \"deploymentEnabled\": true\n  }\n}\n```\n\n### Deployment Flow\n\n1. Push to `main` branch triggers automated preview/production deployments\n2. Each app deploys from its app-level root (e.g., `apps/marketing` for marketing)\n3. No manual `vercel deploy` steps required\n\n## Creating Missing Projects\n\n### `integratewise-live-web` (Product App)\n\n1. Go to Vercel Dashboard → `spine-workspace-2a626284` team\n2. Create project:\n   - **Project Name**: `integratewise-live-web`\n   - **Import from Git**: `https://github.com/integratewise/integratewise-live`\n   - **Root Directory**: `apps/web` (configure in project settings)\n   - **Framework Preset**: Next.js (auto-detected)\n   - **Build Command**: `pnpm run build`\n   - **Install Command**: `pnpm install --frozen-lockfile`\n\n3. Environment variables (inherit from team):\n   - `NEXT_PUBLIC_*` vars: sync from root monorepo settings\n   - `AUTH_*` vars: inherited team scope\n\n4. Custom Domains (after first deployment):\n   - Add `app.integratewise.ai` → production domain\n   - Marketing routes requests for `/app/*` to this project\n\n## Domain Routing\n\n### Apex Domain: `integratewise.ai`\n\nRoute all traffic to the **marketing** project:\n\n```\nintegratewise.ai → integratewise-live-marketing\n```\n\n### Marketing landing subdomains\n\nPublic solution landing hosts also route to the **marketing** project. The\nproject's host-conditional rewrites render the matching solution at the host\nroot, without turning the host into an authenticated Workbench projection.\n\n```text\ncustomer-success.integratewise.ai → /solutions/customer-success\nfinance.integratewise.ai          → /solutions/finance\nproduct-engineering.integratewise.ai → /solutions/product-engineering\n…                                 → matching public solution page\n```\n\nAdd every hostname listed in `apps/marketing/lib/solution-taxonomy.ts` to the\nmarketing Vercel project and configure its DNS record before release. Do not\nadd `brandstore`, `book-of-records`, or `orgmemory`: those are internal-only\noperational concepts, not public marketing pages.\n\n### App Subdomain: `app.integratewise.ai`\n\nRoute to the **web** project:\n\n```\napp.integratewise.ai → integratewise-live-web\n```\n\n### Portfolio Subdomain: `portfolio.integratewise.ai`\n\nRoute to the **portfolio** project:\n\n```\nportfolio.integratewise.ai → integratewise-live-portfolio\n```\n\n## Canonical Connector Ownership\n\nEach service maintains a single canonical connection via Spine:\n\n- **Platform web app** (`integratewise-live-web`): identity authority, Gateway contracts, workspace discovery\n- **Marketing** (`integratewise-live-marketing`): public site, read-only connectors, platform link-outs\n- **Portfolio** (`integratewise-live-portfolio`): standalone showcase, no Spine integration\n\nUser sign-in flow:\n\n1. Sign in via marketing or app subdomain\n2. Session credential issued by platform/web (`POST /api/v1/auth/session`)\n3. Shared `iw_session` cookie honored across all subdomains (domain: `.integratewise.ai`)\n4. Connectors (Vercel, Railway, Cloudflare) communicate through platform only — never directly to marketing or portfolio\n\n## Troubleshooting\n\n### Marketing Previews Canceled\n\n**Root cause**: `git.deploymentEnabled: false` in `apps/marketing/vercel.json`\n\n**Fix**: Set to `true` (already applied in this branch)\n\n### New Project Deployments Fail\n\n1. Verify root directory in Vercel settings (e.g., `apps/web` not `.`)\n2. Check environment variables are synced from team scope\n3. Confirm `NEXT_PUBLIC_*` vars match root `package.json` env.d.ts exports\n\n### Domain Routing Not Working\n\n1. Add DNS CNAME records pointing subdomains to Vercel:\n   - `app.integratewise.ai` → `cname.vercel-dns.com.`\n   - `portfolio.integratewise.ai` → `cname.vercel-dns.com.`\n2. Verify custom domain in each Vercel project's settings\n3. Check Vercel project links are correct (right root directory, right Git branch)\n\n## References\n\n- [Vercel Monorepo Support](https://vercel.com/docs/concepts/monorepos/monorepos-and-root-directory)\n- [Vercel Environment Variables](https://vercel.com/docs/build-output-api/v3/concepts/environment-variables)\n- [Vercel Custom Domains](https://vercel.com/docs/concepts/projects/domains)\n"}