📝 Infrastructure: How to prevent backend-vitto-api from silently failing on Ra...

Date: 2026-03-31
Time: 19:05:21 UTC
Session: gspace1-290.24
Agent: backend
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How to prevent backend-vitto-api from silently failing on Railway when critical env vars are missing?

Task: Vitto prod/dev/staging separation

🎯 Decision Made

Chosen:

Fail-fast validation in main.ts before NestFactory.create — check VITTO_MONGODB_URI, JWT_SECRET, SYSTEM_TOKEN, BACKEND_AI_API_URL on Railway/production, exit(1) if missing

Options Considered:

1. Fail-fast in main.ts before NestFactory.create
2. Health endpoint dependency checking (readiness probe)
3. ConfigModule Joi validation schema
4. Startup guard in AppModule onModuleInit

💭 Reasoning

Root cause: Railway health check returns ok without checking any dependencies. Server boots, passes health check, then silently fails on first real request when BACKEND_AI_API_URL defaults to localhost. The WebSocket client in handoff-ws-client.service.ts detects Railway+localhost and silently skips connection — Vitto accepts tasks but can't delegate to agents. Option 1 (fail-fast in main.ts) is superior because: (a) it runs before any module initialization so no partial boot state, (b) it's 5 lines with zero dependencies, (c) covers both production and staging Railway environments, (d) doesn't change health endpoint semantics (which Railway uses for liveness). Options 2-4 are heavier: health endpoint overhaul would duplicate existing /engine/status observability, Joi schema adds a dependency, and onModuleInit runs too late (some modules already initialized). This decision would be wrong if: Railway changes PORT detection so isRailway is false, or if a new required env var is added but not listed. Early warning: monitor Railway deploy logs for the FATAL message.

📁 Files Involved

• APIs/backend-vitto-api/src/main.ts
• APIs/backend-vitto-api/src/app/connectivity/handoff-ws-client.service.ts

🔗 Related

• Decision ID: dev_1774983921306_89fj8hi
• Session: 290
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation