Deploying to Vercel
Relevant source files
The following files were used as context for generating this wiki page:
Isabella Villaseñor AI utilizes a hybrid architecture for deployment on Vercel, combining a Single Page Application (SPA) frontend with an Express-based backend served via serverless functions. The system uses Vite 6 for the frontend build and a serverless handler to delegate API requests to the Express application defined in server.ts.
This deployment strategy ensures that the application maintains sovereignty and territorial context while benefiting from Vercel's global infrastructure. The configuration handles routing, security headers, and environment validation to ensure a secure, high-performance production environment.
Sources: README.md:144-154, AGENTS.md:8-12
Build and Project Configuration
The project uses pnpm as the canonical package manager for all build operations. Vercel is configured to recognize the Vite framework and use the dist directory for output. The build process involves two primary steps: compiling the React frontend via Vite and bundling the Express server using esbuild into a CommonJS format compatible with Node.js environments.
Sources: package.json:14-17, vercel.json:2-6, README.md:120-131
Key Build Commands
| Command | Purpose | Source |
|---|---|---|
pnpm install | Deterministic installation of dependencies using the lockfile. | package.json:11-17 |
npm run build | Executes vite build and esbuild server.ts to generate production assets. | package.json:15 |
pnpm run verify | Runs linting (TSC), tests (Vitest), and the build process to ensure production readiness. | package.json:20 |
Vercel Function Settings
API routes are handled by a catch-all serverless function located at api/[...path].ts. This function is configured with a maximum duration of 55 seconds to accommodate long-running cognitive inference or quantum mesh execution tasks.
Sources: vercel.json:7-11, README.md:148-154
Routing and Request Delegation
Vercel handles routing through rewrites defined in vercel.json. All paths starting with /api/ are forwarded to the serverless handler, while all other paths serve the index.html file to support client-side routing in the React SPA.
Sources: vercel.json:12-15
The diagram shows how Vercel routes incoming traffic either to the frontend SPA or to the backend Express server via the serverless handler.
Sources: vercel.json:12-15, server.ts:162-166
Security Headers and Content Policy
The Vercel deployment enforces a strict security posture through HTTP headers. These headers prevent cross-site scripting (XSS), framing attacks, and content sniffing. The Content Security Policy (CSP) is specifically configured to allow connections to Isabella's sovereign services, including Supabase, Statsig, and Pollinations AI for neural canvas generation.
Sources: vercel.json:16-56, server.ts:153-161
Production Security Headers
| Header | Value / Purpose | Source |
|---|---|---|
Content-Security-Policy | Restricts sources for scripts, styles, and connections. | vercel.json:20 |
X-Frame-Options | Set to DENY to prevent clickjacking. | vercel.json:44 |
Strict-Transport-Security | Enforces HTTPS for 2 years (63072000 seconds). | vercel.json:52 |
X-Content-Type-Options | Set to nosniff to prevent MIME-type sniffing. | vercel.json:40 |
Environment and Runtime Integration
The deployment requires several critical environment variables to be set in the Vercel dashboard. The application uses assertStrictEnv() during startup to validate that all required production keys are present, failing immediately if the environment is misconfigured.
Sources: server.ts:133-134, README.md:156-163
Integration with External Services
The Express server initializes multiple services during the Vercel cold-start or execution phase:
- PostgreSQL/Supabase: Connects to the database via
DATABASE_URLand runs migrations. - Stripe: Synchronizes the product catalog if
STRIPE_SECRET_KEYis present. - Authz-Runtime: Connects to a Policy Decision Point (PDP) sidecar if
ISABELLA_AUTHZ_RUNTIME_URLis configured. - Native Auth: Bootstraps the Ed25519 public key for Zero-Trust session validation.
Sources: server.ts:139-145, server.ts:1143-1168, README.md:151-154
Deployment Lifecycle
This sequence illustrates the automated deployment flow from code push to serverless invocation.
Sources: package.json:15, vercel.json:2-6, README.md:120-131, AGENTS.md:8-12
Summary
Deploying Isabella Villaseñor AI to Vercel provides a scalable, secure environment that leverages pnpm for deterministic builds and Express for complex backend logic. By utilizing a serverless handler for API requests and a strictly configured CSP, the platform maintains sovereign control over its cognitive and quantum modules while serving a high-performance React frontend to users. Success in production depends on valid environment configurations and passing the comprehensive verify build chain.
Sources: README.md:179-204, AGENTS.md:19-27