backend/app/platform/config.py

@@ -0,0 +1,19 @@
+"""Configuration surface — the single place deployment/environment config is read.
+
+INV-8: no deployment shape is baked into framework code. Every URL, credential, or
+relay coordinate arrives through here from the environment (resolved from Secret
+Manager in deployed environments). The localhost defaults match compose.yaml so a
+clean `scripts/dev.sh` checkout needs no env setup.
+"""
+from __future__ import annotations
+
+import os
+
+# Dev default points at the single Postgres container compose.yaml brings up. In
+# PPE/Prod the deployment supplies ECOMM_DATABASE_URL from Secret Manager (INV-8).
+_DEFAULT_DATABASE_URL = "postgresql://ecomm:ecomm@localhost:5432/ecomm"
+
+
+def database_url() -> str:
+    """The psycopg DSN for the application database."""
+    return os.environ.get("ECOMM_DATABASE_URL") or _DEFAULT_DATABASE_URL

backend/tests/test_config.py

@@ -0,0 +1,13 @@
+import os
+
+from app.platform import config
+
+
+def test_database_url_defaults_to_local_compose(monkeypatch):
+    monkeypatch.delenv("ECOMM_DATABASE_URL", raising=False)
+    assert config.database_url() == "postgresql://ecomm:ecomm@localhost:5432/ecomm"
+
+
+def test_database_url_honors_env(monkeypatch):
+    monkeypatch.setenv("ECOMM_DATABASE_URL", "postgresql://x:y@db:5432/z")
+    assert config.database_url() == "postgresql://x:y@db:5432/z"