Web App Build & Deploy Guide

Lessons from the Cadence Project

Overview

This guide documents the complete process of building and deploying a full-stack web application using Claude Code on a Chromebook. The Cadence task management app was built in two sessions totaling approximately 8 hours.

Final Stack:

• Frontend: React + Vite (hosted on Vercel)
• Backend: Express.js + Node.js (hosted on Railway)
• Database: PostgreSQL (hosted on Railway)
• Email: Resend

Live URLs:

• App: https://cadence.advisoryos.ai
• API: https://cadence-api.advisoryos.ai

Phase 1: Environment Setup (Chromebook)

Enable Linux on Chromebook

1. Settings → Advanced → Developers → Linux development environment
2. Turn on and wait for installation

Install Node.js

sudo apt update
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs -y

Verify:

node --version
npm --version

Install Claude Code

sudo npm install -g @anthropic-ai/claude-code

Authenticate Claude Code

claude

• Select "Anthropic account" when prompted
• Opens browser for authentication
• Requires Claude Pro subscription

Phase 2: Project Creation

Start a New Project

mkdir ~/project-name
cd ~/project-name
claude

Planning Interview

Claude Code will ask about:

• Structure: Monorepo (recommended - single repo with /client and /server folders)
• Auth: JWT tokens (recommended - stateless with access/refresh tokens)
• Language: JavaScript (simpler) or TypeScript

Auto-Approval Settings

Speed up development by allowing Claude Code to auto-approve common commands:

• npm install
• npm run dev
• node --check
• sqlite3 (or database commands)
• curl
• pkill
• git add

Phase 3: Development Workflow

Starting Development Servers

cd ~/project-name
npm run dev

This typically runs both:

• Frontend: http://localhost:5173
• Backend: http://localhost:3001

Giving Instructions to Claude Code

Be specific and detailed:

Good instruction:

Add a forgot password feature:
1. POST /api/auth/forgot-password - accepts email, generates reset token
2. POST /api/auth/reset-password - accepts token and new password
3. Add frontend pages for both flows
4. Add "Forgot password?" link on login page

Vague instruction (avoid):

Add password reset

When Claude Code Gets Stuck

• Press Esc to interrupt
• Try a simpler, more specific command
• Exit with exit and restart with claude
• Do the task manually if needed

Phase 4: Git & GitHub

Initialize Git

git init
git add .
git commit -m "Initial commit"

Create GitHub Repository

1. Go to https://github.com/new
2. Create repo (can be private)
3. Don't initialize with README

Generate Personal Access Token

1. Go to https://github.com/settings/tokens/new
2. Name it (e.g., "project-name")
3. Expiration: 7-90 days
4. Check repo scope
5. Generate and copy token

Push to GitHub

git remote add origin https://github.com/USERNAME/REPO.git
git push -u origin master

When prompted:

• Username: your-github-username
• Password: paste the token (won't show as you type)

Subsequent Pushes

git add .
git commit -m "Description of changes"
git push origin master

Phase 5: Deployment

Backend: Railway

Initial Setup:

1. Go to https://railway.app
2. Sign in with GitHub
3. Click New Project → Deploy from GitHub repo
4. Select your repository
5. In Settings, set Root Directory to server

Add PostgreSQL:

1. Inside your project, press Ctrl + K
2. Type "postgres" and select "Add PostgreSQL"
3. Click on your backend service → Variables
4. Click New Variable → Add Reference → select Postgres DATABASE_URL

Required Environment Variables:

Custom Domain:

1. Service → Settings → Networking/Domains
2. Add custom domain (e.g., api.yourdomain.com)
3. Add CNAME record in your DNS provider

Frontend: Vercel

Initial Setup:

1. Go to https://vercel.com
2. Sign in with GitHub
3. Click Add New Project
4. Import your repository
5. Set Root Directory to client
6. Framework Preset: Vite

Required Environment Variables:

Custom Domain:

1. Project → Settings → Domains
2. Add your domain
3. Add CNAME record: your-subdomain → cname.vercel-dns.com

vercel.json (in client folder):

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": "vite",
  "rewrites": [{"source": "/(.*)", "destination": "/index.html"}]
}

CORS Configuration

The backend must allow requests from the frontend domain. In server/src/index.js:

app.use(cors({
  origin: ['https://your-frontend-domain.com', 'http://localhost:5173'],
  credentials: true
}));

Phase 6: Troubleshooting

Deployment Not Working?

The #1 Lesson: Sometimes you need to wait. Deployments, DNS, and SSL all take time to sync. If you've done everything right, step away for 10-15 minutes.

Common Issues & Fixes

Vercel Won't Auto-Deploy?

Manually redeploy:

1. Go to Deployments tab
2. Click three dots on latest → Redeploy
3. Uncheck "Use existing build cache"

Check API Health

curl https://your-api-domain.com/api/health

Should return: {"status":"ok"}

View All Users (Admin)

curl https://your-api-domain.com/api/admin/users

Delete a User (Admin)

curl -X DELETE https://your-api-domain.com/api/admin/users/USER_ID

Test API Endpoint Directly

curl -X POST https://your-api-domain.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@test.com","password":"Test1234!"}'

Key Terminal Commands Reference

Navigation

cd ~/project-name          # Go to project folder
pwd                        # Show current directory
ls                         # List files

Claude Code

claude                     # Start Claude Code
exit                       # Exit Claude Code
# Press Esc to interrupt a stuck command

Git

git status                 # Check what's changed
git add .                  # Stage all changes
git commit -m "message"    # Commit with message
git push origin master     # Push to GitHub
git log --oneline -5       # View last 5 commits

View/Edit Files (without nano)

cat filename               # View entire file
cat filename | head -20    # View first 20 lines
cat filename | grep "text" # Search for text in file

Edit Files with sed

sed -i 's/old-text/new-text/' filename

Check if Server is Running

curl https://your-api-domain.com/api/health

Project Checklist

Before Starting

• [ ] Linux enabled on Chromebook
• [ ] Node.js installed
• [ ] Claude Code installed and authenticated
• [ ] GitHub account ready
• [ ] Railway account (sign in with GitHub)
• [ ] Vercel account (sign in with GitHub)
• [ ] Domain ready (if using custom domain)
• [ ] Resend account (if using email)

Before Deploying

• [ ] All features working locally
• [ ] Git repository initialized
• [ ] Code pushed to GitHub
• [ ] vercel.json configured in client folder
• [ ] CORS includes production frontend URL

After Deploying

• [ ] Environment variables set in Railway
• [ ] Environment variables set in Vercel
• [ ] Custom domains configured (if using)
• [ ] CNAME records added to DNS
• [ ] SSL certificates provisioned (wait 5-15 min)
• [ ] Test registration and login
• [ ] Test all major features

Costs

Next Project Template

When starting your next project, tell Claude Code:

Create a [type of app] with:
- React frontend with [specific features]
- Express backend with JWT authentication
- PostgreSQL database
- These main features: [list features]

Use the same monorepo structure as Cadence with /client and /server folders.

Guide created from the Cadence build sessions, January 25-26, 2026