🏗️ Architecture: How should Railway git-based deployments handle branch-speci...

Date: 2026-01-23
Time: 15:21:30 UTC
Session: editor2-63.5
Agent: backend
Confidence: 90%
Status: ✅ Documented

📋 Decision Context

Question:

How should Railway git-based deployments handle branch-specific configurations like railway.toml?

Task: Railway deployment branch strategy

🎯 Decision Made

Chosen:

Branch-specific railway.toml in each deploy branch

Options Considered:

1. Single railway.toml with environment variables
2. Branch-specific railway.toml in each deploy branch
3. Dynamically generate railway.toml during deployment
4. Use Railway CLI instead of git-based deployment

💭 Reasoning

Railway's git-based deployment reads railway.toml from the pushed branch. Each backend (api, ai-api, docs-api) needs different Dockerfile paths, start commands, and health check endpoints. By keeping branch-specific railway.toml files in each deploy branch, we can: 1) Push any branch to trigger the correct build, 2) Avoid complex CI/CD logic, 3) Let Railway auto-detect config from the branch. The trade-off is deploy branches will always be slightly ahead of session (by the railway.toml config), but this is acceptable since session is for development, not deployment.

📁 Files Involved

• railway.toml
• deployment/railway.backend-ai.toml
• deployment/railway.docs-api.toml
• deployment/railway.backend.toml

🔗 Related

• Decision ID: dev_1769181690662_i49p1e8
• Session: 63
• Workspace: editor2

Auto-generated by MCP Smart Consolidation