1 Runbooks

sscoble edited this page 2026-05-02 13:41:10 -07:00

Table of Contents

• Runbooks
• 1. How to Deploy
• Prerequisites
• Backend
• Frontend
• Verify Deployment
• Production Deployment Plan (Future)
• 2. How to Add New Products to the Database
• Method A: Seed Script (Development)
• Method B: Direct SQL Insert (Production)
• Style Tags Reference
• Color Groups
• 3. How to Add a New Style Profile
• 4. How to Troubleshoot Common Issues
• Server Won't Start
• Database Errors
• CORS Errors in Frontend
• Feedback API Returns 400
• Matches Return Empty Array
• 5. How to Monitor System Health
• API Health
• Feedback Analysis
• Database Size

Runbooks

Operational guides for deploying, maintaining, and troubleshooting WardrobeAI.

---

1. How to Deploy

Prerequisites

• Node.js (v18+)
• npm

Backend

# Navigate to backend directory
cd wardrobe-ai/backend

# Install dependencies
npm install

# Start server (port 3002)
npm start

The database is automatically initialized on startup. Tables are created via CREATE TABLE IF NOT EXISTS statements in backend/src/db/init.js.

Frontend

# In a separate terminal
cd wardrobe-ai/frontend

# Install dependencies
npm install

# Start dev server (port 3003)
npm run dev

Verify Deployment

# Health check
curl http://localhost:3002/health
# → {"status":"ok","timestamp":"..."}

# Seed sample data (first time only)
curl -X POST http://localhost:3002/seed

# Access frontend
open http://localhost:3003

Production Deployment Plan (Future)

1. Backend → Railway or Fly.io

   • Set PORT environment variable
   • Configure SQLite or switch to PostgreSQL
   • Set up persistent volume for database file

2. Frontend → Vercel

   • Set API_BASE_URL to production backend URL
   • Build: npm run build
   • Deploy via Vercel CLI or GitHub integration

3. Domain → Configure DNS pointing to frontend

---

2. How to Add New Products to the Database

Method A: Seed Script (Development)

1. Edit backend/src/data/sampleInventory.js
2. Add a new item object following the existing format:

{
  id: "item_021",                    // Sequential ID
  name: "Product Name",              // Display name
  price: 59.99,                      // Price in USD (REAL)
  category: "tops",                  // Category: tops, bottoms, dresses, outerwear
  colors: ["blue", "white"],         // Array of colors
  styles: ["casual", "classic"],     // Array of style tags
  brand: "BrandName",                // Source brand
  image: "/images/product.jpg",      // Image path
  description: "Product description" // Short description
}

3. Re-seed the database:

curl -X POST http://localhost:3002/seed

Method B: Direct SQL Insert (Production)

INSERT INTO inventory_items (id, name, price, category, colors, styles, brand, description, image_path)
VALUES ('item_021', 'Product Name', 59.99, 'tops', '["blue", "white"]', '["casual", "classic"]', 'BrandName', 'Description', '/images/product.jpg');

Style Tags Reference

Valid style tags:

• professional, business formal, business casual
• casual, bohemian, classic, preppy
• elegant, evening, formal, modern
• edgy, festive, feminine, summer

Color Groups

The matching engine groups similar colors:

Group	Colors
Black	black, charcoal, dark gray
White	white, ivory, cream
Blue	blue, navy, teal, sky blue
Red	red, burgundy, crimson
Green	green, olive, emerald, teal
Purple	purple, lavender, violet, plum
Gray	gray, silver, slate
Brown	brown, khaki, beige, tan, olive
Neutral	beige, khaki, cream, ivory

---

3. How to Add a New Style Profile

Edit backend/src/data/sampleProfiles.js:

{
  id: "profile_006",
  name: "Profile Name",
  description: "Description of the style profile",
  budget: 150,
  mustHaveCategories: ["tops", "bottoms"],
  preferredStyles: ["professional", "classic"],
  colors: ["black", "navy", "white"],
  excludedStyles: ["bohemian"],
  maxPrice: 100,
  seasons: ["spring", "fall"]
}

Re-seed:

curl -X POST http://localhost:3002/seed

---

4. How to Troubleshoot Common Issues

Server Won't Start

Symptoms: Error: listen EADDRINUSE :::3002

Solution:

# Find process using port
lsof -i :3002

# Kill it
kill -9 <PID>

# Or use a different port
PORT=3003 npm start

Database Errors

Symptoms: SQLITE_ERROR: no such table

Solutions:

• Delete the database file and restart:

  rm backend/database/wardrobe-ai.db
  npm start  # Auto-recreates tables
  

• Re-seed: curl -X POST http://localhost:3002/seed

CORS Errors in Frontend

Symptoms: Frontend can't reach backend API (browser console shows CORS error)

Solutions:

• Ensure backend is running on port 3002
• Check frontend/lib/config.js has the correct API_BASE_URL
• Backend has cors() middleware enabled — verify it's importing correctly
• For development, both services must be on localhost (not 127.0.0.1 mixed)

Feedback API Returns 400

Symptoms: POST /feedback returns {"error": "boxId and feedback are required"}

Solutions:

• Ensure boxId is a string, not an object
• Ensure feedback is an array of objects, each with itemId, at minimum
• Validate JSON structure matches the API reference

Matches Return Empty Array

Symptoms: GET /profiles/:id/matches returns {"matches": []}

Solutions:

• Verify the profile exists: curl http://localhost:3002/profiles
• Check that inventory items have been seeded: curl http://localhost:3002/inventory
• Ensure at least one item's styles/colors overlap with the profile's preferences
• If all items are excluded by excluded_styles, no matches will be returned

---

5. How to Monitor System Health

API Health

# Quick health check
curl -s http://localhost:3002/health | jq .

# Check database is populated
curl -s http://localhost:3002/profiles | jq '.profiles | length'
curl -s http://localhost:3002/inventory | jq '.items | length'

Feedback Analysis

# See what feedback has been collected
curl -s http://localhost:3002/feedback/analysis | jq .

Database Size

ls -lh backend/database/wardrobe-ai.db