Deployment Skill

Read .hackathon/STACK.md for deployment targets and .hackathon/STATE.md for current status.

Hard gate: Scaffold must be complete.
Soft gate: If phase-plan is not complete, warn that deployment is premature but allow it (useful for testing the pipeline early).

Deployment Strategy for Hackathons

When to Deploy

• After scaffold: Optional "smoke test" deployment to verify the pipeline works. Worth 10 minutes to avoid a 60-minute crisis at demo time.
• After Phase 2 (Integration): First real deployment. The primary flow should work.
• Before demo: Final deployment with all features.

Deployment Priorities

1. It must work for 5 minutes. Hackathon demos are short. Uptime of 99.9% doesn't matter. What matters is it works during your 2-minute demo.
2. One-command deploy. If deployment takes more than one command, script it.
3. Environment variables. Every secret must be in env vars, not code. The .env.example file from scaffolding should document everything needed.
4. Fallback plan. If deployment fails, localhost demo must work. If localhost fails, recorded video must exist.

Process

Step 1: Verify Prerequisites

• All environment variables are set
• Build passes locally (pnpm build)
• No TypeScript errors (pnpm typecheck)

Step 2: Deploy Backend

Based on stack choice:

• Railway: Connect repo, set env vars, deploy
• Fly.io: Use Dockerfile, fly deploy
• Vercel Serverless: Configure as serverless functions
• Local + ngrok: Last resort, but works for demo

Step 3: Deploy Frontend

Based on stack choice:

• Vercel: Connect repo, auto-deploy
• Netlify: Similar to Vercel
• Same platform as backend: If using Railway/Fly for fullstack

Step 4: Verify End-to-End

• Frontend loads at the deployed URL
• Frontend can reach the deployed backend
• A representative user flow works

Step 5: Create Deploy Script

Save the commands as scripts/deploy.sh so subsequent deploys are one command.

Output

• Deployed application with URL(s)
• scripts/deploy.sh for repeatable deploys
• Updated .env.example with any new variables needed for deployment
• Update STATE.md
• Log deployment URL to changelog
• Print: "Deployed! Frontend: [url] | Backend: [url]"