Settings architecture: switch from inheritance to composition (pydantic-settings best practice)

[madebygps]

Settings architecture: switch from inheritance to composition (pydantic-settings best practice)

Tracking follow-up to PR introducing 3-class Settings split with Environment enum (branch refactor/settings-decoupled).

Context

The current refactor uses class inheritance to share settings between three runtime profiles:

DatabaseSettings           (alembic, migration job)
  └── WorkerSettings       (verification-functions)
        └── WebSettings    (api webapp)

Each level adds fields. A registry (configure_settings() + get_*_settings()) lets entry-points pick their profile and shared modules pull the right typed accessor.

This works, but research during the implementation surfaced that composition is the recommended pydantic-settings v2 pattern, not inheritance.

Research findings

Three credible sources, one consistent answer:

Source	Position
Official pydantic-settings docs (https://docs.pydantic.dev/latest/concepts/pydantic_settings/)	Shows composition (nested BaseModel as field values, env_nested_delimiter="__") as the primary documented pattern. Inheritance is shown only for single-class env_prefix examples.
Industry guidance (multiple blog posts and Stack Overflow answers from pydantic v2 era)	Explicitly recommends composition over inheritance. Cited reasons: clear namespace (settings.database.url vs settings.db_url), modularity, no field-name collisions, reusable sub-configs. Inheritance described as "error-prone with multiple inheritance" and "harder to scale."
FastAPI+Celery monorepo guidance (closest analog to our 3-process setup)	Recommends one shared Settings class in common/; configuration differences come from environment variables, not class hierarchy.

Why the current inheritance design is sub-optimal

1. Pydantic-settings is built for composition. The whole env_nested_delimiter="__" mechanism exists for nested config models. Inheritance treats configuration as a class hierarchy problem; composition treats it as a data-structure problem (which is what it actually is).

2. The IS-A relationship doesn't hold semantically. "Webapp IS-A worker" reads cleanly as English but it's a category error in code. The webapp and the worker are peer processes that share some config fields; one isn't a subtype of the other.

3. Fields leak. A WebSettings instance has labs_verification_secret on it, even though no webapp code uses that field. The type checker can't say "this field only matters in the worker." With composition, the webapp's settings simply don't reference a LabsConfig sub-config (or it has whatever subset it actually uses).

4. Validators end up in the wrong place. Our _validate_web lives on WebSettings. If we ever needed a validator that depends on BOTH a worker field and a web field, it'd live on WebSettings and be invisible from WorkerSettings even though the worker has those fields too. With composition, validators live on the sub-model they validate.

5. The registry is a smell. configure_settings() + get_database_settings() / get_worker_settings() / get_web_settings() exists because Python doesn't naturally express "this process wants only the DB part of settings, please skip the OAuth validator." That's because inheritance is the wrong tool. With composition, each process instantiates a different top-level Settings class that only references the sub-configs it needs — no registry, no isinstance checks.

Proposed design

# Reusable sub-configs — small, focused, single source of truth per concern.

class DatabaseConfig(BaseModel):
    url: str = ""
    host: str = ""
    port: int = 5432
    database: str = "learntocloud"
    user: str = ""
    pool_size: int = 5
    # ... etc

    @model_validator(mode="after")
    def _validate(self) -> Self:
        if not self.url and not (self.host and self.user):
            raise ValueError("Database configuration required.")
        return self


class GitHubConfig(BaseModel):
    """Server-to-server GitHub API access."""
    token: str = ""


class OAuthConfig(BaseModel):
    """User-facing OAuth login flow."""
    client_id: str = ""
    client_secret: str = ""


class LabsConfig(BaseModel):
    verification_secret: str = ""
    external_api_timeout: float = 15.0


# Three top-level Settings classes — one per process. NO inheritance.
# Each picks the sub-configs it actually uses.

class MigrationSettings(BaseSettings):
    """Loaded by api/alembic/env.py."""
    model_config = SettingsConfigDict(env_file=".env", env_nested_delimiter="__", extra="ignore")
    database: DatabaseConfig = DatabaseConfig()


class WorkerSettings(BaseSettings):
    """Loaded by apps/verification-functions/function_app.py."""
    model_config = SettingsConfigDict(env_file=".env", env_nested_delimiter="__", extra="ignore")
    database: DatabaseConfig = DatabaseConfig()
    github: GitHubConfig = GitHubConfig()
    labs: LabsConfig = LabsConfig()


class WebSettings(BaseSettings):
    """Loaded by api/src/learn_to_cloud/main.py."""
    model_config = SettingsConfigDict(env_file=".env", env_nested_delimiter="__", extra="ignore")
    environment: Environment = Environment.PRODUCTION
    database: DatabaseConfig = DatabaseConfig()
    github: GitHubConfig = GitHubConfig()
    labs: LabsConfig = LabsConfig()
    oauth: OAuthConfig = OAuthConfig()
    session_secret_key: str = "dev-secret-key-change-in-production"
    # ... web-specific fields

Each process instantiates its own top-level class directly. No registry. No configure_settings() global. No isinstance checks.

Migration scope (this is why it's a separate PR)

Switching to composition is a coordinated change that touches:

1. Every call site — settings.database_url becomes settings.database.url, settings.github_token becomes settings.github.token, etc. About 30+ access patterns across api + shared + verification-functions.

2. Every environment variable name:

   • api/.env.example: DATABASE_URL → DATABASE__URL, GITHUB_CLIENT_ID → OAUTH__CLIENT_ID, etc.
   • apps/verification-functions/local.settings.json
   • infra/migrations.tf (env vars on the migration job)
   • infra/container-apps.tf (env vars on the api container app)
   • infra/functions.tf (env vars on the verification-functions Functions app)
   • .github/workflows/deploy.yml
   • Azure Key Vault references — the secret names may need to change

3. Coordinated production deploy. The new env vars must be set in prod BEFORE the new code rolls out. Otherwise the app fails to start because DATABASE__URL isn't found, only the old DATABASE_URL exists. Options:

   • Two-phase deploy: deploy infra with BOTH old and new env var names; deploy code that reads only new names; deploy infra removing old names. Three releases, low risk.
   • Single-phase with backfill: configure code to fall back to old names (AliasChoices) for one release, then remove the fallback.

4. Test rewrites. All WebSettings(field=value) constructions become WebSettings(database=DatabaseConfig(url=...)) style. About a dozen test fixtures + test_config.py rewrites.

5. get_*_settings() accessors and configure_settings() registry go away. Replaced with direct instantiation at each entry-point: _settings = WebSettings() in api/main.py, MigrationSettings() in env.py, WorkerSettings() in function_app.py.

Recommendation

Treat this as a dedicated PR after the current refactor/settings-decoupled work lands. The current inheritance design is functional, documented as a known sub-optimal pattern, and unblocks the immediate goal (kill the DEBUG=true hack). The composition rewrite is a quality improvement that deserves its own focused review and its own coordinated deploy.

Cross-references

• Current implementation branch: refactor/settings-decoupled
• Companion: Alembic tooling improvements — remaining Tiers 2–4 #449 (alembic improvements) — same hygiene-driven theme
• Related: Database design improvements — remaining Tiers 2–4 #448 (DB design improvements)
• Source for the recommendation: https://docs.pydantic.dev/latest/concepts/pydantic_settings/#nested-settings-models
• Industry context: discussion of composition vs inheritance in pydantic-settings v2 across SO/blog posts during 2024-2026

[madebygps]

Copilot session notes

Session date: 2026-05-26
Related work: PR #500, PR #501, PR #502, final deployed commit 59cc305
Model used: GPT-5.5, model ID gpt-5.5
Token usage: Not available
MCP/tool servers used: Context7, Tavily, GitHub CLI, local shell and file tools
Skills used: debug-deploy; issue-session-notes instructions followed from .github/skills/issue-session-notes/SKILL.md

What we learned

• The pydantic-settings v2 nested model pattern worked best with BaseSettings only at the top level and smaller BaseModel config objects underneath it.
• Double underscore environment variables, such as DATABASE__URL and CONTENT__DIR, were the safest naming choice because many field names already contain single underscores, such as client_id, secret_key, and base_url.
• Nested aliases on inner BaseModel classes were not reliable enough for flat environment variable fallback. The temporary compatibility layer had to copy old flat values into nested dictionaries at the top-level settings model.
• The compatibility layer was useful for the first rollout, but it needed a follow-up PR so the codebase would not keep supporting two configuration styles forever.
• Firecrawl was not available in this environment. Research used Context7 and Tavily, and the built-in web search tool was not used.

Mistakes or false starts

• The first production deploy after removing the compatibility layer failed because one image-level default still used the old CONTENT_DIR name. The code now required CONTENT__DIR.
• The failure happened in the deploy workflow's Build and Push Container Images step, before migrations and before app rollout, so production was not partially updated by that failed run.
• A local container smoke test could not be run because Docker was not installed in this environment. The replacement deploy itself verified the exact Docker path in GitHub Actions.

Important implementation details

• PR Refactor settings into composed config models #500 refactored settings from inheritance to composition.
• PR Remove flat settings compatibility layer #501 removed the temporary flat environment variable compatibility layer after the app, infrastructure, CI, and local examples were moved to nested __ names.
• PR Fix migration image content directory setting #502 fixed the deploy failure by changing the migration image default from CONTENT_DIR="/app/content/phases" to CONTENT__DIR="/app/content/phases".
• The replacement deploy run 26405532398 passed CI, Terraform, verification Functions deployment, image build and push, database migrations, Container App rollout, and readiness checks.
• Keep learner curriculum examples that mention DATABASE_URL separate from this app's runtime settings. Those examples are for student projects, not the production app configuration.

Next action

• None. Issue Settings architecture: switch from inheritance to composition (pydantic-settings best practice) #450 and its follow-up cleanup are merged and deployed.