📚 Documentation: How to resolve the apps/ vs APIs/ path mismatch in Railway d...

Date: 2026-02-28
Time: 13:50:53 UTC
Session: gspace1-148.2
Agent: documentation
Confidence: 100%
Status: ✅ Documented

📋 Decision Context

Question:

How to resolve the apps/ vs APIs/ path mismatch in Railway deployment configs after the directory rename?

Task: Comprehensive deployment documentation cleanup after apps/ to APIs/ rename and Railway consolidation

🎯 Decision Made

Chosen:

Fix all deployment configs and documentation comprehensively

Options Considered:

1. Only fix railway.toml files
2. Fix all deployment configs and documentation comprehensively
3. Rename APIs/ back to apps/ to avoid the mismatch

💭 Reasoning

The apps/ directory was renamed to APIs/ but deployment files (railway.toml, deployment-config.js, deploy.sh scripts, and all deployment documentation) still referenced the old paths. This caused Railway builds to fail because: (1) railway.toml startCommand overrides Dockerfile CMD, and when it pointed to dist/apps/ while NX built to dist/APIs/, the service couldn't start; (2) The deploy CLI safety check rejected deployments when deployment-config.js and railway.toml paths didn't match. Fixed: all 4 railway.toml canonical configs, deployment-config.js, all 4 deploy.sh scripts, RAILWAY_DEPLOYMENT_GUIDE.md (complete rewrite), RAILWAY-GITHUB-DEPLOYMENT.md (complete rewrite), RAILWAY-CONSOLIDATION-MIGRATION-GUIDE.md (status update), BACKEND-AI-API-DEPLOYMENT.md, and Backend-AI-Api/index.md. Key lesson: when renaming source directories, ALL downstream paths must be updated: project.json outputPath, Dockerfile CMD/test, railway.toml startCommand, deployment-config.js, deploy.sh scripts, watchPatterns, and documentation.

📁 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/cli/lib/deployment-config.js
• deployment/backend-api/deploy.sh
• deployment/backend-ai-api/deploy.sh
• deployment/backend-docs-api/deploy.sh
• deployment/backend-vitto-api/deploy.sh
• deployment/docs/RAILWAY_DEPLOYMENT_GUIDE.md
• docs/english/Deployment/RAILWAY-GITHUB-DEPLOYMENT.md
• deployment/docs/RAILWAY-CONSOLIDATION-MIGRATION-GUIDE.md

🔗 Related

• Decision ID: dev_1772286653604_oszfb3h
• Session: 148
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation