Skip to main content

ADR-025: 12-Factor App Compliance

Status​

Implemented

Date​

2025-01-16 (Retrospective)

Decision Makers​

  • Architecture Team - Application design
  • DevOps Team - Deployment patterns

Layer​

Infrastructure

  • ADR-010: Docker Compose Development
  • ADR-046: Environment Configuration

Supersedes​

None

Depends On​

None

Context​

Modern cloud-native applications benefit from standardized practices:

  1. Portability: Run anywhere (local, cloud, Kubernetes)
  2. Scalability: Horizontal scaling without code changes
  3. Maintainability: Clear separation of concerns
  4. Operations: Predictable deployment behavior
  5. Team Efficiency: Common patterns reduce onboarding time

The 12-Factor App methodology provides these standards.

Decision​

We follow the 12-Factor App methodology for application design:

Key Design Decisions​

  1. Full Compliance: All 12 factors implemented
  2. Environment Variables: Primary configuration mechanism
  3. Stateless Processes: No local session state
  4. Docker First: Containerization as default
  5. Log Streaming: stdout/stderr output

Factor Implementation​

#FactorImplementation
ICodebaseSingle monorepo, Git version control
IIDependenciesuv/npm lock files, explicit declarations
IIIConfigEnvironment variables, .env files
IVBacking ServicesPostgreSQL, Redis as attached resources
VBuild, Release, RunDocker images, CI/CD pipeline
VIProcessesStateless FastAPI/React, Redis for state
VIIPort BindingSelf-contained, uvicorn/nginx exposure
VIIIConcurrencyProcess scaling via container replicas
IXDisposabilityFast startup/shutdown, graceful termination
XDev/Prod ParityDocker Compose mirrors production
XILogsstructlog to stdout, aggregation external
XIIAdmin ProcessesAlembic migrations, management commands

Configuration Pattern​

# backend/core/config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    # Factor III: Store config in the environment
    database_url: str
    redis_url: str = "redis://localhost:6379/0"
    secret_key: str
    environment: str = "development"
    log_level: str = "INFO"

    class Config:
        env_file = ".env"

Backing Services (Factor IV)​

# All backing services are attached resources
services:
  backend:
    environment:
      DATABASE_URL: postgresql://...
      REDIS_URL: redis://...
      OPENAI_API_KEY: ${OPENAI_API_KEY}

Process Model (Factor VIII)​

# kubernetes deployment
spec:
  replicas: 3  # Horizontal scaling
  template:
    spec:
      containers:
      - name: backend
        resources:
          limits:
            memory: "512Mi"

Consequences​

Positive​

  • Cloud Native: Works with any platform (AWS, GCP, K8s)
  • Scalable: Add replicas without code changes
  • Portable: Same app runs locally and in production
  • Debuggable: Consistent behavior everywhere
  • Team Ready: Industry-standard patterns

Negative​

  • Initial Setup: More configuration upfront
  • Statelessness Constraint: Must use external state
  • Environment Sprawl: Many variables to manage
  • Learning Curve: Methodology understanding needed

Neutral​

  • Trade-offs: Some flexibility for standardization
  • Legacy Integration: May need adapters

Alternatives Considered​

1. Monolithic Deployment​

  • Approach: Traditional server-based deployment
  • Rejected: Less scalable, environment-specific

2. Serverless Only​

  • Approach: Functions as a Service
  • Rejected: Cold start issues, stateful operations

3. PaaS Lock-in​

  • Approach: Platform-specific patterns (Heroku, etc.)
  • Rejected: Vendor lock-in, limited flexibility

Implementation Status​

  • Core implementation complete
  • Tests written and passing
  • Documentation updated
  • Migration/upgrade path defined
  • Monitoring/observability in place

Implementation Details​

  • Config: backend/core/config.py
  • Dependencies: pyproject.toml, package.json
  • Docker: docker-compose.yml, docker/
  • Migrations: backend/migrations/
  • Logging: backend/core/logging_config.py
  • Docs: docs/archived/deployment/12-factor.md

Compliance/Validation​

  • Automated checks: CI validates environment portability
  • Manual review: Factor compliance reviewed quarterly
  • Metrics: None (architectural pattern)

LLM Council Review​

Review Date: 2025-01-16 Confidence Level: High (100%) Verdict: CONDITIONALLY APPROVE AS "12-FACTOR ALIGNED"

Quality Metrics​

  • Consensus Strength Score (CSS): 0.88
  • Deliberation Depth Index (DDI): 0.85

Council Feedback Summary​

Unanimous recommendation to shift from "Full Compliance" to "Pragmatic Alignment." An internal SRE platform has different constraints than public-facing SaaS apps the 12-Factor methodology was designed for.

Key Concerns Identified:​

  1. Factor VIII (Concurrency) Overkill: SRE platforms deal with complex logic, not massive request volume; async + pod autoscaling usually sufficient
  2. Factor X (Dev/Prod Parity) Too Rigid: 100% parity (HA databases locally) is expensive; focus on "Behavioral Parity"
  3. Env Vars for Secrets is Risky: Secrets in process environment can leak; use Secrets Manager (Vault/AWS/K8s Secrets)

Required Modifications:​

  1. Soften Compliance Goal: "Adopt principles where they improve operability; document intentional deviations"
  2. Split State Strategy:
    • Stateless compute layer
    • Postgres for durable workflow state
    • Redis for ephemeral caching/locking only
  3. Add Modern Factors:
    • Factor 13: Observability (Metrics + Traces, not just Logs)
    • Factor 14: Security By Design (RBAC, SBOMs, vulnerability scanning)
    • Factor 15: API First (OpenAPI contracts)
    • Factor 16: Graceful Degradation (health checks, circuit breakers, SIGTERM handling)
  4. Secrets Management: Require injection from Secrets Manager, not just pydantic-settings reading .env

Modifications Applied​

  1. Documented pragmatic alignment approach
  2. Added modern factors (Observability, Security, API First, Graceful Degradation)
  3. Documented secrets management requirement
  4. Clarified state strategy (Postgres vs Redis)

Council Ranking​

  • claude-opus-4.5: Best Response (modern factors)
  • gemini-3-pro: Strong (state strategy)
  • gpt-5.2: Good (secrets management)

References​

ADR-025 | Infrastructure Layer | Implemented