Development Workflow

The complete guide to developing, versioning, and deploying your ArchitectGBT project.

Recommended Workflow

After downloading your generated project, follow this professional workflow:

1. Download & Extract

Download the ZIP from ArchitectGBT
Extract to your workspace
Navigate to the project folder

2. Install & Run Locally

cd my-project
npm install
cp .env.example .env.local
# Add your API keys to .env.local
npm run dev

3. Initialize Git

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

4. Create GitHub Repository

Option A: Using GitHub CLI

gh repo create my-project --public --source=. --remote=origin --push

Option B: Using GitHub.com

Go to github.com/new
Create repository (same name as your project)
Don't initialize with README (you already have files)
Copy the commands shown:

git remote add origin https://github.com/yourusername/my-project.git
git branch -M main
git push -u origin main

5. Connect Vercel to GitHub

This is the recommended approach (better than direct deployment):

Go to vercel.com
Click Add New → Project
Import Git Repository
Select your GitHub repo
Configure settings:
- Framework Preset: Next.js (auto-detected)
- Build Command: npm run build
- Output Directory: .next
Add environment variables
Click Deploy

6. Development Cycle

Now you have automatic deployments! Every time you push to GitHub:

# Make your changes locally
# Edit files in your code editor

# Test locally
npm run dev

# Commit changes
git add .
git commit -m "Add feature X"

# Push to GitHub
git push

# Vercel automatically deploys! 🚀

Why Git + Vercel Integration?

✅ Benefits

Automatic Deployments - Push to deploy
Preview Deployments - Each PR gets a preview URL
Easy Rollbacks - Revert to any previous deployment
Team Collaboration - Multiple developers can work together
Version History - Track all changes
CI/CD Ready - Add tests, linting, etc.

❌ vs Direct Deployment

Direct deployment (via API token) is:

One-time only
No version control
Hard to update
No collaboration
Manual redeployments

Branch Strategy

Simple Project (Solo Developer)

main → Production (Vercel auto-deploys)

Team Project

main → Production
develop → Staging
feature/* → Preview deployments

Environment Variables

Development (.env.local)

# Local development only
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

Production (Vercel Dashboard)

# Production keys
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
CLERK_SECRET_KEY=sk_live_...

Vercel automatically uses production env vars when deploying.

Making Changes

Adding Features

Create a new branch:

git checkout -b feature/new-landing-page

Make changes locally
Test:

npm run dev
npm run build  # Test production build

Commit and push:

git add .
git commit -m "Add new landing page"
git push origin feature/new-landing-page

Create Pull Request on GitHub
Review preview deployment (Vercel creates one automatically)
Merge to main → Auto-deploys to production! 🎉

Updating Dependencies

npm update
npm audit fix

# Test locally
npm run dev

# Commit and push
git add package.json package-lock.json
git commit -m "Update dependencies"
git push

Changing AI Model

Edit your API routes:

// src/app/api/chat/route.ts
import { anthropic } from '@ai-sdk/anthropic';

// Change model
model: anthropic('claude-3-5-sonnet-20241022')
// to
model: anthropic('claude-opus-4-5')

Commit and push - Vercel redeploys automatically.

Rollback Strategy

Quick Rollback (Vercel Dashboard)

Go to Deployments
Find the working version
Click ••• → Promote to Production

Git Rollback

# See commit history
git log --oneline

# Revert to specific commit
git revert <commit-hash>
git push

# Or reset (careful!)
git reset --hard <commit-hash>
git push --force

Collaboration Workflow

Adding Team Members

Add to GitHub repository (Settings → Collaborators)
Add to Vercel project (Settings → Team)
Share environment variables securely

Working Together

# Developer 1
git checkout -b feature/auth
# Make changes
git push origin feature/auth

# Developer 2
git checkout -b feature/dashboard
# Make changes
git push origin feature/dashboard

# Both get preview deployments
# Merge when ready

Advanced: Custom Domains

Add Your Domain

Buy domain (Namecheap, GoDaddy, etc.)
In Vercel: Settings → Domains
Add domain: app.yourdomain.com
Update DNS records as shown
Wait for SSL (automatic)

Update URLs

# .env.local (development)
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Vercel (production)
NEXT_PUBLIC_APP_URL=https://app.yourdomain.com

Monorepo Setup (Advanced)

If you have multiple projects:

my-workspace/
├── apps/
│   ├── web/          # Your ArchitectGBT project
│   └── api/          # Separate backend
└── packages/
    └── shared/       # Shared code

Each can deploy independently to Vercel.

Continuous Integration

Add GitHub Actions

Create .github/workflows/test.yml:

name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm run build
      - run: npm run lint

Best Practices

Commit Messages

# Good
git commit -m "Add email validation to signup form"
git commit -m "Fix: Resolve authentication redirect loop"
git commit -m "Update: Upgrade to Next.js 16"

# Bad
git commit -m "changes"
git commit -m "fix"
git commit -m "update"

Branch Naming

feature/user-dashboard
bugfix/login-redirect
hotfix/security-patch
chore/update-dependencies

Code Review Checklist

[ ] Code builds successfully
[ ] Tests pass (if you have them)
[ ] Preview deployment looks correct
[ ] Environment variables updated
[ ] README updated if needed
[ ] No sensitive data in code

Troubleshooting

Push Rejected

# Pull latest changes first
git pull origin main
# Resolve conflicts if any
git push

Deployment Failed

Check build logs in Vercel dashboard
Verify environment variables
Test npm run build locally
Check for TypeScript errors

Preview Not Working

Verify Vercel GitHub integration
Check repository permissions
Ensure vercel.json is correct

Quick Reference

# Daily workflow
git pull                    # Get latest
# Make changes
npm run dev                 # Test locally
git add .                   # Stage changes
git commit -m "message"     # Commit
git push                    # Deploy

# Branch workflow
git checkout -b feature/x   # New branch
# Make changes
git push origin feature/x   # Push branch
# Create PR on GitHub
# Merge → Auto-deploy

Resources

Next: Back to Quick Start →

Quick Links