OnyxMunk/AudioForge

1# AudioForge – Finalization & Deployment Plan
2
3**Date**: February 2, 2026  
4**Goal**: Polish code, fix bugs, make production-ready, deploy to Vercel, attach custom domain  
5**Custom domain**: `yourdomain.com` → **replace with your real domain** when adding in Vercel
6
7---
8
9## Architecture Overview
10
11- **Frontend**: Next.js 14 (App Router) → Deploy to **Vercel**
12- **Backend**: FastAPI (Python) → Deploy separately (Railway, Render, Fly.io) – *not Vercel*
13- **Database**: PostgreSQL (Supabase or managed)
14- **Redis**: For caching (optional for MVP)
15
16---
17
18## Phase 1: Analyze & Polish ✅
19
20### 1.1 Fix Missing Lib Modules (Blocking Build)
21- [x] Create `frontend/src/lib/utils.ts` – `cn()` classnames helper (clsx + tailwind-merge)
22- [x] Create `frontend/src/lib/api.ts` – API client with `GenerationRequest`, `GenerationResponse`, `generationsApi` (create, list)
23
24### 1.2 Code Quality
25- Run `pnpm run build` in frontend – fix any build errors
26- Run `pnpm run lint` and `pnpm run type-check` – fix linter/TypeScript errors
27- Remove stray `console.log`, add error boundaries if needed
28- Improve loading states (low-hanging fruit)
29
30### 1.3 Accessibility
31- Basic a11y checks on main interactive elements (buttons, forms, audio player)
32
33---
34
35## Phase 2: Pre-Deploy Checks ✅
36
37### 2.1 Environment & Config
38- [x] Create/update `frontend/.env.example` with `NEXT_PUBLIC_API_URL`
39- [x] Verify `.gitignore` – never commit `.env`, `node_modules`
40- [x] Create `vercel.json` if needed (rewrites, redirects, root directory for monorepo)
41
42### 2.2 Vercel-Specific
43- **Root directory**: `frontend` (monorepo – backend is separate)
44- **Build command**: `pnpm run build` (or `npm run build`)
45- **Output directory**: `.next` (Next.js default)
46- **Env vars**: `NEXT_PUBLIC_API_URL` → your deployed backend URL
47
48---
49
50## Phase 3: Deployment Execution
51
52### 3.1 Git & Repo
531. Ensure git remote exists (GitHub/GitLab)
542. Commit all changes: `chore: pre-deployment polish & fixes`
553. Push to `main` (or preferred branch)
56
57### 3.2 Vercel Deploy
581. Go to [vercel.com](https://vercel.com) → New Project → Import Git Repository
592. Configure:
60   - **Root Directory**: `frontend`
61   - **Framework Preset**: Next.js
62   - **Build Command**: `pnpm run build` (or `npm run build`)
63   - **Environment Variables**: Add `NEXT_PUBLIC_API_URL` = `https://your-backend-url.com`
643. Deploy
654. Copy preview URL (e.g. `https://audioforge-xxx.vercel.app`)
66
67### 3.3 Backend Deployment (Required for Full Functionality)
68- Deploy FastAPI backend to Railway, Render, or Fly.io
69- Set `CORS_ORIGINS` to include your Vercel URL and custom domain (comma-separated)
70- Set `NEXT_PUBLIC_API_URL` in Vercel to your backend URL
71- Redeploy frontend after backend is live
72
73### 3.4 Custom Domain
741. Vercel Dashboard → Project → **Settings** → **Domains**
752. Add domain: `yourdomain.com` and `www.yourdomain.com`
763. Configure DNS (at your registrar):
77   - **A record**: `@` → `76.76.21.21`
78   - **CNAME**: `www` → `cname.vercel-dns.com`
794. Wait for DNS propagation (5–60 min)
805. Vercel will auto-provision SSL
81
82---
83
84## Phase 4: Verification & Handover
85
86- Visit deployed URL in browser
87- Test: load page, submit a generation (if backend is live)
88- If issues: diagnose, fix, redeploy
89- **Final output**: Live URL + custom domain instructions
90
91---
92
93## Risks & Mitigations
94
95| Risk | Mitigation |
96|------|------------|
97| Backend not deployed | Frontend will load but API calls fail; document backend deployment steps |
98| CORS issues | Backend CORS_ORIGINS must include Vercel domain |
99| WebSocket over HTTPS | Ensure backend supports WSS if frontend is HTTPS |
100| Monorepo structure | Use Vercel root directory `frontend` |
101
102---
103
104## Commands Reference
105
106```bash
107# Frontend build (from project root)
108cd frontend && pnpm run build
109
110# Frontend dev
111cd frontend && pnpm run dev
112
113# Lint & type-check
114cd frontend && pnpm run lint && pnpm run type-check
115
116# Run tests
117cd frontend && pnpm run test
118```
119
120---
121
122## Files Created/Modified
123
124| File | Action |
125|------|--------|
126| `frontend/src/lib/utils.ts` | Create |
127| `frontend/src/lib/api.ts` | Create |
128| `frontend/.env.example` | Create |
129| `vercel.json` (root) | Create |
130| `PLAN.md` | Create (this file) |
131
132---
133
134**Next**: Execute Phase 1–2, then deploy.
135