SourcAI — Deployment Guide

SourcAI — Deployment Guide

Architecture

[Browser] → [Railway: sourcai-frontend] → [Railway: sourcai-backend] → [Claude API]
                                                    ↓
                                          [Persistent Volume: /app/workspace-volume]

• Frontend: Next.js 14 on Railway (auto-deploy from main, root: frontend/)
• Backend: FastAPI on Railway (auto-deploy from main, root: backend/)
• Storage: Railway persistent volume at /app/workspace-volume — survives redeploys
• No tunnel needed. Both services on Railway with fixed URLs.

URLs

Railway IDs

How it works

1. Push to main → Railway auto-deploys both services
2. Backend Dockerfile strips claude-agent-sdk (macOS-only wheel) and re-locks deps for Linux
3. entrypoint.sh seeds the persistent volume with git-baked request data (datasets, templates, CLAUDE.md, existing requests) — only copies what doesn’t already exist in the volume
4. New requests created at runtime persist in the volume between deploys
5. Frontend reads NEXT_PUBLIC_API_URL env var → points to Railway backend (fixed URL)

Local development

cd /Users/styreep/cofoundy/projects/starthack-2026/backend
uv run uvicorn app.main:app --port 8000

To point the live frontend at your local backend for testing:

https://sourcai-frontend-production.up.railway.app/?api=http://localhost:8000

Verify

# 1. Backend health
curl https://sourcai-backend-production.up.railway.app/health

# 2. Processed requests
curl https://sourcai-backend-production.up.railway.app/api/requests | python3 -c "import json,sys; print(f'{len(json.load(sys.stdin))} requests')"

# 3. Frontend loads
curl -s -o /dev/null -w "HTTP %{http_code}" https://sourcai-frontend-production.up.railway.app/

Demo mode fallback

When the backend is unreachable, the frontend automatically enters demo mode:

• Shows 5 mock processed requests
• Shows 8 mock dataset requests with working filters
• Agent run uses animated mock data
• All tabs (New Request, Dataset, Processed) are functional

WARNING: Demo mode is silent — no banner or indicator. If you see generic data (Dell Precision 5690, always the same 3 suppliers), you’re in demo mode. Always verify with the health check.

localStorage gotcha

The frontend stores the API URL in localStorage['sift_api_url']. This takes priority over the env var. If anyone previously visited with ?api=SOME_OLD_TUNNEL_URL, their browser will keep hitting that dead URL.

Fix: Visit once with the correct URL to update localStorage:

https://sourcai-frontend-production.up.railway.app/?api=https://sourcai-backend-production.up.railway.app

CI/CD

• Every push to main triggers Railway auto-deploy for both services
• Frontend root: frontend/ — npm install && npx next build
• Backend root: backend/ — Dockerfile with uv
• Next.js 14.2.35 (upgraded from 14.2.21 to fix CVE-2025-55184 and CVE-2025-67779)

Backend env vars (Railway)

Persistent volume details

• Mount path: /app/workspace-volume
• Symlinked to: /app/workspace (via entrypoint.sh)
• Contains: data/ (datasets), requests/REQ-*/ (processed requests), CLAUDE.md (agent prompt), templates/
• Seed logic: On each deploy, entrypoint.sh copies new data from git into the volume without overwriting existing requests