Skip to content

DEPLOYMENT_CHECKLIST.md

Latest commit

 

History

History
365 lines (290 loc) · 7.58 KB

DEPLOYMENT_CHECKLIST.md

File metadata and controls

365 lines (290 loc) · 7.58 KB

🎬 SceneGuard Backend - Deployment Checklist

✅ Pre-Deployment Checklist

1. Dependencies ✅

  • drizzle-orm installed
  • @neondatabase/serverless installed
  • @google/generative-ai installed
  • drizzle-kit installed (dev)
  • zod already present

2. Environment Variables ✅

  • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
  • CLERK_SECRET_KEY
  • GEMINI_API_KEY
  • WEATHER_API_KEY
  • DATABASE_URL (fixed format)

3. Database Schema ✅

  • users table defined
  • scene_analyses table defined
  • analysis_artifacts table defined
  • artifact_type enum defined
  • Foreign key relationships set

4. Business Logic ✅

  • Gemini parser (fact extraction only)
  • Risk analyzer (deterministic rules)
  • Cost analyzer (qualitative)
  • Weather service (Visual Crossing API)
  • Planning insights (templates)

5. API Endpoint ✅

  • POST /api/scene/analyze implemented
  • Auth check with Clerk
  • Input validation with Zod
  • Error handling
  • Database persistence
  • Artifact storage

6. Documentation ✅

  • BACKEND_DOCS.md (API reference)
  • QUICK_START.md (setup guide)
  • IMPLEMENTATION_SUMMARY.md (overview)
  • Code comments throughout

🚀 Deployment Steps

Step 1: Install Dependencies

npm install

Expected output:

added X packages in Xs

Step 2: Generate Database Migrations

npm run db:generate

Expected output:

✓ Generating migrations...
✓ Migrations generated in ./drizzle

Step 3: Push to Neon Database

npm run db:push

Expected output:

✓ Applying migrations...
✓ Schema updated successfully

Verify in Neon Dashboard:

  • Go to https://console.neon.tech
  • Select your project
  • Check Tables tab
  • Confirm: users, scene_analyses, analysis_artifacts exist

Step 4: Start Development Server

npm run dev

Expected output:

▲ Next.js 16.1.6
- Local:    http://localhost:3000
✓ Ready in Xs

🧪 Testing Checklist

Test 1: Simple Indoor Scene

Request:

POST /api/scene/analyze
{
  "sceneDescription": "Interior office, single character at desk",
  "sceneCategory": "Indoor",
  "timeOfDay": "Day"
}

Expected:

  • ✅ Status: 200 OK
  • ✅ Low risk signals
  • ✅ Low cost pressure
  • ✅ No weather data
  • ✅ Indoor planning recommendations

Test 2: Outdoor Scene with Weather

Request:

POST /api/scene/analyze
{
  "sceneDescription": "Park scene with children playing",
  "sceneCategory": "Outdoor",
  "timeOfDay": "Day",
  "location": "Seattle, WA",
  "month": "November"
}

Expected:

  • ✅ Status: 200 OK
  • ✅ Weather dependency risk
  • ✅ Weather feasibility data included
  • ✅ Rain/wind averages
  • ✅ Production recommendations

Test 3: High-Risk Action Scene

Request:

POST /api/scene/analyze
{
  "sceneDescription": "Downtown car chase with explosions, crowds, and stunt drivers",
  "sceneCategory": "Outdoor",
  "timeOfDay": "Night",
  "location": "New York, NY",
  "month": "July"
}

Expected:

  • ✅ Status: 200 OK
  • ✅ Multiple high-risk signals
  • ✅ Multiplier applied (1.3x)
  • ✅ High cost pressure
  • ✅ Multiple cost drivers
  • ✅ Detailed explanations

Test 4: VFX Studio Scene

Request:

POST /api/scene/analyze
{
  "sceneDescription": "Green screen studio, sci-fi spaceship interior",
  "sceneCategory": "VFX"
}

Expected:

  • ✅ Status: 200 OK
  • ✅ No weather data
  • ✅ VFX-specific cost drivers
  • ✅ Studio recommendations
  • ✅ Post-production notes

Test 5: Validation Error

Request:

POST /api/scene/analyze
{
  "sceneDescription": "Outdoor park",
  "sceneCategory": "Outdoor"
}

Expected:

  • ✅ Status: 400 Bad Request
  • ✅ Error: "Outdoor scenes require both location and month"
  • ✅ Detailed validation errors in response

Test 6: Unauthenticated Request

Request: No Clerk token

Expected:

  • ✅ Status: 401 Unauthorized
  • ✅ Error: "Unauthorized"

🔍 Database Verification

Check User Creation

SELECT * FROM users ORDER BY created_at DESC LIMIT 5;

Expected: See user records with clerk_user_id

Check Scene Analyses

SELECT 
  id, 
  scene_description, 
  created_at,
  final_analysis_json->>'sceneMetadata'
FROM scene_analyses 
ORDER BY created_at DESC 
LIMIT 5;

Expected: See analysis records with full JSON

Check Artifacts

SELECT 
  artifact_type,
  COUNT(*) as count
FROM analysis_artifacts
GROUP BY artifact_type;

Expected:

gemini_parse     | 5
risk_engine      | 5
cost_engine      | 5
weather_snapshot | 2  (only for outdoor scenes)

📊 Success Criteria

✅ All systems operational when:

  1. Dependencies installed without errors
  2. Database migrations applied successfully
  3. Development server starts without crashes
  4. API accepts authenticated requests
  5. All test cases return expected responses
  6. Database records are created correctly
  7. Artifacts are stored for each analysis
  8. Error handling works as expected

🐛 Common Issues & Solutions

Issue: "DATABASE_URL is not set"

Solution:

  • Check .env.local exists
  • Verify DATABASE_URL format (no 'psql' prefix)
  • Restart dev server: Ctrl+C then npm run dev

Issue: "Unauthorized" on all requests

Solution:

  • Verify Clerk is configured correctly
  • Check user is logged in
  • Inspect browser dev tools for auth token
  • Verify Clerk middleware is active

Issue: Gemini API errors

Solution:

  • Verify GEMINI_API_KEY in .env.local
  • Check API quota at https://makersuite.google.com
  • Test key with simple curl request
  • Ensure key has Gemini API enabled

Issue: Weather API errors

Solution:

  • Verify WEATHER_API_KEY
  • Check location format: "City, State" or "City, Country"
  • Ensure month is spelled correctly (e.g., "January")
  • Verify API quota at visualcrossing.com

Issue: Database connection errors

Solution:

  • Verify Neon database is active
  • Check connection string format
  • Test connection in Neon dashboard
  • Ensure SSL mode is correct

🎯 Demo Readiness Checklist

Before Showing Judges:

  • All dependencies installed
  • Database migrated successfully
  • Dev server running
  • Tested all 3 scene categories (Indoor, Outdoor, VFX)
  • Verified database records are created
  • Prepared example requests in Postman/Thunder Client
  • Reviewed BACKEND_DOCS.md to answer questions
  • Can explain architecture decisions
  • Can show database records in Neon dashboard
  • Can demonstrate artifact storage

📝 Talking Points for Demo

Architecture

"We built a clean, deterministic backend that prioritizes explainability over complexity."

AI Usage

"Gemini only extracts facts from descriptions. All decisions use rule-based logic, making every recommendation auditable and explainable."

Data Persistence

"Every analysis is stored with complete audit trail. We save intermediate outputs as artifacts so we can trace exactly how each decision was made."

Production-Ready

"This isn't a prototype - it's production-quality code with proper error handling, validation, and type safety throughout."

Scalability

"The modular architecture makes it easy to add new risk types, cost drivers, or analysis dimensions without breaking existing functionality."

🎬 You're Ready!

Complete backend skeleton built for SceneGuard:

  • ✅ Clean architecture
  • ✅ Explainable decisions
  • ✅ Complete auditability
  • ✅ Production-ready quality
  • ✅ Demo-ready functionality

Time to shine at the hackathon! 🌟