Architecture: How should Railway environment variables be organized across...

Documentation for Sessions

🏗️ Architecture: How should Railway environment variables be organized across...

Date: 2026-02-10
Time: 17:01:57 UTC
Session: gspace1-102.6
Agent: documentation
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How should Railway environment variables be organized across 4 separate Railway projects (backend-api, backend-ai-api, backend-docs-api, backend-vitto-api)?

Task: Railway environment variable audit and sync - Session 102.3

🎯 Decision Made

Chosen:

Two sources of truth only: .env.local (gitignored) for local dev, Railway dashboard for production. No committed files with real secret values. .env.local includes inline comments documenting which Railway services need which variables. deployment/docs/ENV_LOCAL_TEMPLATE.md has variable NAMES and placeholders only.

Options Considered:

  1. Create RAILWAY_VARIABLES.md with redacted secrets
  2. Use .env.local as single reference with inline Railway checklist comments
  3. Create a validation script that queries Railway CLI

💭 Reasoning

Each backend is in a separate Railway project, so Railway's native shared variables feature cannot be used across them. Committing secrets to .md files is a security anti-pattern (git history is permanent). The .env.local file serves double duty: actual dev values AND a commented reference of the Railway variable structure. Since it's gitignored, it's safe to include real values and documentation together.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation