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)
- [x] Create `frontend/src/lib/utils.ts` – `cn()` classnames helper (clsx + tailwind-merge)
- [x] 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
- [x] Create/update `frontend/.env.example` with `NEXT_PUBLIC_API_URL`
- [x] Verify `.gitignore` – never commit `.env`, `node_modules`
- [x] 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](https://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

```bash
# 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.