Skip to main content

ADR 003: Railway + Vercel Split Deployment

Date: 2026-04-22 Status: Accepted

Context​

The platform has three services that need to be deployed and operated:

  1. api/ — NestJS backend (needs persistent connections, WebSocket, DB access)
  2. agent/ — Python FastAPI (GPU-optional, longer cold starts acceptable)
  3. frontend/ — Next.js (SSR + static assets, benefits from CDN edge)

Options evaluated:

  • AWS ECS/EKS — full control, high operational overhead, expensive for early stage
  • Render — simpler than AWS, limited WebSocket support, no persistent volumes on cheap tiers
  • Fly.io — good for edge, no managed Postgres/Redis, more config overhead
  • Railway — managed Postgres + Redis, simple deploy from railway.toml, WebSocket support, persistent volumes
  • Vercel — CDN-first, excellent for Next.js, no support for long-running Python or Node processes

Decision​

Railway for all backend services (api, agent, Postgres, Redis) + Vercel for the Next.js frontend.

The split is deliberate:

  • Vercel's edge CDN gives the frontend global performance and zero-config Next.js deployment
  • Railway handles everything that needs persistent connections, a database, or WebSocket support

All backend services are in one Railway project (humanwork), deployed independently via railway up --service <name>. Railway manages:

  • Postgres 16 (with pgvector plugin) — humanwork-postgres
  • Redis 7 — humanwork-redis
  • API service — humanwork-api
  • Agent service — humanwork-agent

CI/CD is via GitHub Actions: test → build → railway up per service → vercel --prod for frontend → smoke test.

Consequences​

Benefits:

  • Railway's managed Postgres eliminates DB operations overhead (backups, failover, pgvector extension installation via init script)
  • railway.toml per service makes deploy config explicit and version-controlled
  • Railway keeps last 5 deployments — rollback is one CLI command
  • Vercel's CDN handles frontend scaling automatically; no capacity planning needed
  • One Railway project = one billing line, simple cost visibility

Trade-offs:

  • Railway is US-West region only currently. Multi-region (PRD target: Asia-Pacific edge) requires migration to AWS or Railway's planned multi-region support. Tracked in BLK-037.
  • Railway has ~2 minute cold starts for the agent service (Python dependency install). Mitigated by keeping the service always-on (no scale-to-zero).
  • Split deployment means two sets of deploy credentials (Railway token + Vercel token) in GitHub Actions secrets.

Region note: Production is deployed to Railway US-West. For Asian mid-market launch, latency from HK/Singapore is acceptable at MVP scale (~150-200ms RTT). AWS AP-Southeast deployment is tracked as BLK-037 for when latency SLAs tighten.

Last updated on by ethumanity