learning_ai_common_plat/docs/devops/vercel/ROADMAP_MINDLYST_WEB.md

MindLyst Web — Vercel Deployment Roadmap

App: mindlyst-web Repo: learning_multimodal_memory_agents → mindlyst-native/web/ Status: ⚠️ Partial — nested path + server-side Cosmos + many env vars

---

Current State

• Framework: Next.js ^16.0.0, React ^19.0.0
• Output: Vercel-aware
• Styling: Vanilla CSS (globals.css with --ml-* custom properties) — no TailwindCSS
• Dependencies: 10 @bytelyst/* — all via Gitea registry ✅ (no file: refs)
• Build: next build (no --webpack flag)
• Server-side: Azure Cosmos DB (direct @azure/cosmos), OpenAI API, extraction-service calls
• Special: Nested repo path (mindlyst-native/web/), uses tsconfig.build.json
• 33 API routes — triage, memory, brains, streaks, reflections, etc.

Gaps to Fix

Gap 1: Registry Access (~5 min)

Once Gitea is deployed to the Azure VM with a public HTTPS URL, update .npmrc.

• Update .npmrc to Azure VM Gitea URL
• Set GITEA_NPM_TOKEN as a Vercel environment variable

Gap 2: Nested Root Directory (~2 min)

Vercel needs to know the app lives at mindlyst-native/web/, not the repo root.

• Set Root Directory in Vercel project settings to mindlyst-native/web

Gap 3: Server-Side Dependencies (~10 min)

The app has 33 API routes that directly query Azure Cosmos DB. All require server-side env vars.

• Configure all required env vars on Vercel (see list below)
• Ensure Cosmos DB firewall allows Vercel's IP ranges (or use 0.0.0.0/0 for serverless)

Gap 4: TypeScript Build Config (~5 min)

Uses tsconfig.build.json for typecheck (tsc --noEmit -p tsconfig.build.json). Vercel's default next build should work without this, but verify.

• Confirm next build succeeds without explicit tsconfig reference

Environment Variables (~10 min)

• COSMOS_ENDPOINT — Azure Cosmos DB endpoint
• COSMOS_KEY — Azure Cosmos DB key
• MINDLYST_USER_ID — Default user ID
• SEED_SECRET — Seed endpoint secret
• OPENAI_API_KEY — OpenAI API key (for triage)
• EXTRACTION_SERVICE_URL — extraction-service endpoint (port 4005)
• PLATFORM_SERVICE_URL — platform-service endpoint (port 4003)
• NEXT_PUBLIC_PLATFORM_URL — client-side platform URL

Deployment Steps

Step 1: Fix registry access (~5 min)

Step 2: Create Vercel Project (~5 min)

• Connect learning_multimodal_memory_agents repo
• Set Root Directory to mindlyst-native/web
• Framework preset: Next.js

Step 3: Configure Environment Variables (~10 min)

Step 4: Verify (~15 min)

• Test dashboard loads (3-pane layout)
• Test brain packs page
• Test triage API (needs OpenAI key)
• Test memory creation flow
• Verify Cosmos connectivity

Step 5: Domain (~5 min)

• Add custom domain (e.g., app.mindlyst.com)

Risks

• Cosmos DB latency: 33 server-side API routes all hit Cosmos. Cold starts will be noticeable.
• OpenAI dependency: Triage API calls OpenAI — needs API key and will incur costs.
• Extraction service: Several routes call extraction-service — must be publicly accessible.
• No ISR/SSG: All pages appear to be dynamic — no static optimization opportunities without refactoring.

Estimated Total Effort: ~40 minutes