🏗️ Architecture: How should ports be configured across multiple workspace clo...

Date: 2026-02-06
Time: 19:32:31 UTC
Session: editor2-97.2
Agent: angular
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How should ports be configured across multiple workspace clones of the same monorepo?

Task: Session 97: Port reorganization for multi-workspace monorepo

🎯 Decision Made

Chosen:

Environment-variable-driven port system using .env.local as single source of truth, with compile-time constants in proxy-config.ts (browser-safe) and runtime resolution in cors.factory.ts (backend-only)

Options Considered:

1. Hardcoded ports in project.json and package.json
2. Environment variable interpolation in project.json (not supported by NX)
3. Runtime process.env resolution in shared library (breaks Angular browser builds)
4. .env.local + dev-serve.js wrapper script for package.json + compile-time constants for browser code

💭 Reasoning

NX does not support env var interpolation in project.json. process.env cannot be used in browser-compiled shared libraries (causes TS2591 in Angular compiler). The solution splits concerns: .env.local holds workspace-specific values, cors.factory.ts reads process.env at runtime (backend-only, safe), proxy-config.ts uses plain compile-time constants (browser-safe), and dev-serve.js resolves ports from .env.local before calling nx serve. This works cross-platform (macOS, Windows, Linux) with zero external dependencies.

📁 Files Involved

• libs/libs-foundational/api-config/src/lib/proxy-config.ts
• libs/libs-api/backend-core/src/lib/config/cors.factory.ts
• .env.local
• tools/scripts/dev-serve.js
• AGENTS.md

🔗 Related

• Decision ID: dev_1770406351372_7hvvfdn
• Session: 97
• Workspace: editor2

Auto-generated by MCP Smart Consolidation