deployment-guide

name	deployment-guide
description	Complete deployment guide for Dr. Sophia AI on Railway. Covers environment-aware build system, frontend dist/ compilation, backend auto-deploy, Railway configuration, troubleshooting build/deployment issues. Use when deploying to Railway, building frontend for production, debugging deployment failures, or setting up environment variables.

Railway Deployment Guide

Overview

Complete guide for deploying Dr. Sophia AI to Railway with environment-aware builds, proper dist/ compilation, and backend auto-deployment. This skill covers the critical differences between frontend and backend deployment workflows.

Keywords: Railway deployment, build process, environment configuration, dist folder, production deployment, frontend build, backend deploy, npm run build

When to Use This Skill

• Deploying frontend to Railway
• Deploying backend to Railway
• Building dist/ folder for production
• Debugging deployment failures
• Setting up environment variables
• Troubleshooting Railway issues

Critical Deployment Fact

🚨 FRONTEND: Railway deploys the pre-built dist/ folder, NOT source files!

• Changing /frontend/src/*.jsx alone = ❌ NO DEPLOYMENT
• Must run npm run build + commit dist/ = ✅ DEPLOYMENT

✅ BACKEND: Railway deploys directly from source (NO build step needed)

Frontend Deployment Process

Step 1: Make Changes

# Edit frontend source files
nano frontend/src/ModernApp.jsx

Step 2: Build (MANDATORY!)

cd frontend
npm run build  # Auto-detects branch, builds for correct environment

What This Does:

• Detects current git branch (dev/main/prototype)
• Sets correct backend URL automatically
• Creates optimized dist/ folder (~55KB)
• Includes password protection
• Injects API keys from .env

Step 3: Verify Build

ls -lh dist/assets/*.css  # Must be ~60KB (not 9KB!)
ls -lh dist/assets/*.js   # Must be ~450KB

Step 4: Commit & Deploy

git add -A                  # Includes BOTH src/ and dist/
git commit -m "feat: your changes"
git push origin dev         # Railway auto-deploys from dist/

Backend Deployment Process

Step 1: Make Changes

# Edit backend files
nano backend/backend-proxy-enhanced-current.js

Step 2: Commit & Deploy (That's It!)

git add backend/
git commit -m "fix: backend improvement"
git push origin dev         # Railway auto-deploys from source

No build step required - Backend runs directly from source.

Environment Detection

Build script automatically detects branch and configures backend URL:

Branch	Frontend URL	Backend URL
dev	frontend-dev-8670.up.railway.app	backend-dev-d231.up.railway.app
main	botaniqal-medtech-frontend.up.railway.app	backend-production-5c38.up.railway.app
prototype	frontend-prototype.up.railway.app	backend-prototype.up.railway.app

Override if needed:

BUILD_ENV=production npm run build  # Force specific environment

Deployment Checklist

Frontend Deployment

• Run npm run build from frontend/ directory
• Verify CSS is ~60KB (not 9KB = Tailwind not working)
• Verify JS is ~450KB
• git add -A (include dist/ folder!)
• Commit with descriptive message
• Push to Railway (auto-deploys)
• Wait 2-3 minutes for build/deploy
• Verify deployment at Railway URL

Backend Deployment

• Edit backend files
• git add backend/
• Commit changes
• Push to Railway (auto-deploys)
• Railway rebuilds automatically
• No build step needed

Common Deployment Failures

Issue	Cause	Fix
Frontend changes don't appear	Forgot to build dist/	Run npm run build
dist/ not deployed	Forgot git add dist/	git add -A includes dist/
CSS broken (tiny file)	Wrong build command	Use npm run build (not npm run build:vite)
Voice feature not working	Missing API keys in dist/config.js	Rebuild with npm run build
Backend points to wrong URL	Built on wrong branch	Check git branch before building

Detailed Documentation

For environment configuration, build troubleshooting, and Railway setup, see:

• Environment Config: references/environment-config.md
• Build Troubleshooting: references/build-troubleshooting.md
• Railway Configuration: references/railway-config.md

Verification Script

Run post-deployment verification:

.claude/skills/deployment-guide/scripts/verify-deployment.sh dev

Expected output:

✅ Backend health check passed
✅ Version matches: v13.2.7
✅ API keys configured

Quick Reference

Frontend Build Commands

cd frontend
npm run build          # Environment-aware (recommended)
BUILD_ENV=dev npm run build     # Force dev environment
BUILD_ENV=production npm run build  # Force production

Backend Version Check

# Check deployed version
curl https://backend-dev-d231.up.railway.app/health | jq .version

# Should match local version
grep "BACKEND_VERSION" backend/backend-proxy-enhanced-current.js

Railway Dashboard

• Dev Frontend: https://railway.app/project/frontend-dev-8670
• Dev Backend: https://railway.app/project/backend-dev-d231
• Prod Frontend: https://railway.app/project/botaniqal-medtech-frontend
• Prod Backend: https://railway.app/project/backend-production-5c38

---

Build System: Environment-aware (auto-detects branch) Deployment: Git push triggers Railway auto-deploy Last Updated: September 21, 2025