Unclassified

Vercel Project Topology

Overview

IntegrateWise 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.

App	Location	Vercel Project	Root Path	Environment	Status
Marketing	`apps/marketing`	`integratewise-live-marketing`	`apps/marketing`	`spineworkspace.com/marketing` → `integratewise.ai`	✅ Active
Web (Product)	`apps/web`	`integratewise-live-web`	`apps/web`	`spineworkspace.com/web` → `app.integratewise.ai`	🔄 Create project

Git Deployment Status

All projects have Git auto-deployment enabled in their vercel.json:

{
  "git": {
    "deploymentEnabled": true
  }
}

Deployment Flow

Push to main branch triggers automated preview/production deployments
Each app deploys from its app-level root (e.g., apps/marketing for marketing)
No manual vercel deploy steps required

Creating Missing Projects

`integratewise-live-web` (Product App)

Go to Vercel Dashboard → spine-workspace-2a626284 team
Create project:
- Project Name: integratewise-live-web
- Import from Git: https://github.com/integratewise/integratewise-live
- Root Directory: apps/web (configure in project settings)
- Framework Preset: Next.js (auto-detected)
- Build Command: pnpm run build
- Install Command: pnpm install --frozen-lockfile
Environment variables (inherit from team):
- NEXT_PUBLIC_* vars: sync from root monorepo settings
- AUTH_* vars: inherited team scope
Custom Domains (after first deployment):
- Add app.integratewise.ai → production domain
- Marketing routes requests for /app/* to this project

Domain Routing

Apex Domain: `integratewise.ai`

Route all traffic to the marketing project:

integratewise.ai → integratewise-live-marketing

Marketing landing subdomains

Public solution landing hosts also route to the marketing project. The
project's host-conditional rewrites render the matching solution at the host
root, without turning the host into an authenticated Workbench projection.

customer-success.integratewise.ai → /solutions/customer-success
finance.integratewise.ai          → /solutions/finance
product-engineering.integratewise.ai → /solutions/product-engineering
…                                 → matching public solution page

Add every hostname listed in apps/marketing/lib/solution-taxonomy.ts to the
marketing Vercel project and configure its DNS record before release. Do not
add brandstore, book-of-records, or orgmemory: those are internal-only
operational concepts, not public marketing pages.

App Subdomain: `app.integratewise.ai`

Route to the web project:

app.integratewise.ai → integratewise-live-web

Portfolio Subdomain: `portfolio.integratewise.ai`

Route to the portfolio project:

portfolio.integratewise.ai → integratewise-live-portfolio

Canonical Connector Ownership

Each service maintains a single canonical connection via Spine:

Platform web app (integratewise-live-web): identity authority, Gateway contracts, workspace discovery
Marketing (integratewise-live-marketing): public site, read-only connectors, platform link-outs
Portfolio (integratewise-live-portfolio): standalone showcase, no Spine integration

User sign-in flow:

Sign in via marketing or app subdomain
Session credential issued by platform/web (POST /api/v1/auth/session)
Shared iw_session cookie honored across all subdomains (domain: .integratewise.ai)
Connectors (Vercel, Railway, Cloudflare) communicate through platform only — never directly to marketing or portfolio

Troubleshooting

Marketing Previews Canceled

Root cause: git.deploymentEnabled: false in apps/marketing/vercel.json

Fix: Set to true (already applied in this branch)

New Project Deployments Fail

Verify root directory in Vercel settings (e.g., apps/web not .)
Check environment variables are synced from team scope
Confirm NEXT_PUBLIC_* vars match root package.json env.d.ts exports

Domain Routing Not Working

Add DNS CNAME records pointing subdomains to Vercel:
- app.integratewise.ai → cname.vercel-dns.com.
- portfolio.integratewise.ai → cname.vercel-dns.com.
Verify custom domain in each Vercel project's settings
Check Vercel project links are correct (right root directory, right Git branch)