🏗️ Architecture: How should we organize deployment configs for 4 backend APIs...

Date: 2026-02-09
Time: 18:09:29 UTC
Session: gspace1-101.3
Agent: backend
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How should we organize deployment configs for 4 backend APIs in a monorepo to prevent cross-contamination?

Task: Restructure deployment infrastructure for 4 Railway services

🎯 Decision Made

Chosen:

Per-service subdirectories: deployment/{service}/ each containing Dockerfile.railway, railway.toml (canonical), deploy.sh, and README.md. Deploy CLI copies canonical toml to repo root and validates before push.

Options Considered:

1. Keep flat deployment/ directory with prefixed filenames (status quo)
2. Per-service subdirectories in deployment/ with canonical railway.toml
3. Per-app deployment configs inside each apps/ directory

💭 Reasoning

The flat directory caused the Session 101 incident where deploy/api got the wrong railway.toml. Per-service dirs provide: (1) clear ownership - each service's config lives together, (2) canonical source of truth - the CLI always copies from the service dir, never relies on merge results, (3) self-documenting - each dir has its own README with domain, branch, env vars, (4) validation hook - CLI validates toml content matches target before push.

📁 Files Involved

• deployment/backend-api/railway.toml
• deployment/backend-ai-api/railway.toml
• deployment/backend-docs-api/railway.toml
• deployment/backend-vitto-api/railway.toml
• deployment/README.md
• tools/scripts/deployment/lib/deployment-config.js
• tools/scripts/deployment/lib/branch-manager.js
• tools/scripts/deployment/railway-deploy-cli.js

🔗 Related

• Decision ID: dev_1770660569226_6mi4nfx
• Session: 101
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation