PLAN.md

AudioForge – Finalization & Deployment Plan

Date: February 2, 2026
Goal: Polish code, fix bugs, make production-ready, deploy to Vercel, attach custom domain
Custom domain: yourdomain.com → replace with your real domain when adding in Vercel

---

Architecture Overview

• Frontend: Next.js 14 (App Router) → Deploy to Vercel
• Backend: FastAPI (Python) → Deploy separately (Railway, Render, Fly.io) – not Vercel
• Database: PostgreSQL (Supabase or managed)
• Redis: For caching (optional for MVP)

---

Phase 1: Analyze & Polish ✅

1.1 Fix Missing Lib Modules (Blocking Build)

• Create frontend/src/lib/utils.ts – cn() classnames helper (clsx + tailwind-merge)
• Create frontend/src/lib/api.ts – API client with GenerationRequest, GenerationResponse, generationsApi (create, list)

1.2 Code Quality

• Run pnpm run build in frontend – fix any build errors
• Run pnpm run lint and pnpm run type-check – fix linter/TypeScript errors
• Remove stray console.log, add error boundaries if needed
• Improve loading states (low-hanging fruit)

1.3 Accessibility

• Basic a11y checks on main interactive elements (buttons, forms, audio player)

---

Phase 2: Pre-Deploy Checks ✅

2.1 Environment & Config

• Create/update frontend/.env.example with NEXT_PUBLIC_API_URL
• Verify .gitignore – never commit .env, node_modules
• Create vercel.json if needed (rewrites, redirects, root directory for monorepo)

2.2 Vercel-Specific

• Root directory: frontend (monorepo – backend is separate)
• Build command: pnpm run build (or npm run build)
• Output directory: .next (Next.js default)
• Env vars: NEXT_PUBLIC_API_URL → your deployed backend URL

---

Phase 3: Deployment Execution

3.1 Git & Repo

1. Ensure git remote exists (GitHub/GitLab)
2. Commit all changes: chore: pre-deployment polish & fixes
3. Push to main (or preferred branch)

3.2 Vercel Deploy

1. Go to vercel.com → New Project → Import Git Repository
2. Configure:
   • Root Directory: frontend
   • Framework Preset: Next.js
   • Build Command: pnpm run build (or npm run build)
   • Environment Variables: Add NEXT_PUBLIC_API_URL = https://your-backend-url.com
3. Deploy
4. Copy preview URL (e.g. https://audioforge-xxx.vercel.app)

3.3 Backend Deployment (Required for Full Functionality)

• Deploy FastAPI backend to Railway, Render, or Fly.io
• Set CORS_ORIGINS to include your Vercel URL and custom domain (comma-separated)
• Set NEXT_PUBLIC_API_URL in Vercel to your backend URL
• Redeploy frontend after backend is live

3.4 Custom Domain

1. Vercel Dashboard → Project → Settings → Domains
2. Add domain: yourdomain.com and www.yourdomain.com
3. Configure DNS (at your registrar):
   • A record: @ → 76.76.21.21
   • CNAME: www → cname.vercel-dns.com
4. Wait for DNS propagation (5–60 min)
5. Vercel will auto-provision SSL

---

Phase 4: Verification & Handover

• Visit deployed URL in browser
• Test: load page, submit a generation (if backend is live)
• If issues: diagnose, fix, redeploy
• Final output: Live URL + custom domain instructions

---

Risks & Mitigations

Risk	Mitigation
Backend not deployed	Frontend will load but API calls fail; document backend deployment steps
CORS issues	Backend CORS_ORIGINS must include Vercel domain
WebSocket over HTTPS	Ensure backend supports WSS if frontend is HTTPS
Monorepo structure	Use Vercel root directory frontend

---

Commands Reference

# Frontend build (from project root)
cd frontend && pnpm run build

# Frontend dev
cd frontend && pnpm run dev

# Lint & type-check
cd frontend && pnpm run lint && pnpm run type-check

# Run tests
cd frontend && pnpm run test

---

Files Created/Modified

File	Action
frontend/src/lib/utils.ts	Create
frontend/src/lib/api.ts	Create
frontend/.env.example	Create
vercel.json (root)	Create
PLAN.md	Create (this file)

---

Next: Execute Phase 1–2, then deploy.