12-Factor App Compliance Analysis

Reference: The Twelve-Factor App

Overview

The 12-Factor App methodology is a set of best practices for building Software-as-a-Service applications that are:

Portable across execution environments Scalable without architectural changes Suitable for continuous deployment Maintainable with minimal friction Input Parameters Parameter Description Required codebase_path Root path of the codebase to analyze Required Analysis Framework Factor I: Codebase

Principle: One codebase tracked in revision control, many deploys.

Search Patterns:

Check for version control

ls -la .git 2>/dev/null || ls -la .hg 2>/dev/null

find . -name "package.json" -o -name "pyproject.toml" -o -name "setup.py" | head -20

Check for environment-specific code branches

grep -r "if.production|if.development|if.staging" --include=".py" --include=".js" --include=".ts"

File Patterns: .git/, package.json, pyproject.toml, deployment configs

Compliance Criteria:

Level Criteria Strong Single Git repo, same codebase for all environments, no env-specific code branches Partial Single repo but some environment-specific code paths Weak Multiple repos for same app or significant code duplication across environments

Anti-patterns:

Multiple Git repositories for the same application Environment-specific code branches (if production: ...) Different source files for dev vs prod Shared code not extracted to libraries Factor II: Dependencies

Principle: Explicitly declare and isolate dependencies.

Search Patterns:

Python dependency files

find . -name "requirements.txt" -o -name "pyproject.toml" -o -name "setup.py" -o -name "Pipfile" -o -name "uv.lock"

JavaScript/TypeScript dependency files

find . -name "package.json" -o -name "package-lock.json" -o -name "yarn.lock" -o -name "pnpm-lock.yaml"

Check for system tool assumptions

grep -r "subprocess.curl|subprocess.wget|os.system.ffmpeg|shutil.which" --include=".py" grep -r "exec.curl|child_process.curl" --include=".js" --include=".ts"

Docker/container isolation

find . -name "Dockerfile" -o -name "docker-compose*.yml"

File Patterns: /requirements*.txt, /package.json, /*.lock, /Dockerfile

Compliance Criteria:

Level Criteria Strong Lock files present, dependency isolation (venv/Docker), no implicit system tools Partial Dependencies declared but no lock files or isolation Weak Dependencies in documentation only, relies on system-installed packages

Anti-patterns:

Missing lock files (non-deterministic builds) Assuming system tools (curl, ImageMagick, ffmpeg) are available Different dependency managers in dev vs production No virtual environment or container isolation Factor III: Config

Principle: Store config in the environment.

Search Patterns:

Environment variable usage

grep -r "os.environ|os.getenv|process.env|ENV[" --include=".py" --include=".js" --include=".ts" --include=".rb"

Hardcoded credentials (anti-pattern)

Environment-specific config files (anti-pattern)

find . -name "config.dev." -o -name "config.prod." -o -name "settings.development." -o -name "settings.production."

Database URLs in code

File Patterns: /.env*, /config/.py, */settings.py, environment files

Compliance Criteria:

Level Criteria Strong All config via environment variables, no hardcoded secrets, could open-source without leaks Partial Most config externalized but some hardcoded defaults Weak Hardcoded credentials, environment-specific config files

Anti-patterns:

Hardcoded database URLs, API keys, passwords in source Config files like config/production.yml vs config/development.yml Environment grouping (if ENV == 'production': ...) Secrets committed to version control Factor IV: Backing Services

Principle: Treat backing services as attached resources.

Search Patterns:

Database connection via config

grep -r "DATABASE_URL|DB_HOST|REDIS_URL|CACHE_URL" --include=".py" --include=".js" --include="*.ts"

Service initialization

Hardcoded service locations (anti-pattern)

File Patterns: /database/*.py, /services/.py, */db.py, connection configurations

Compliance Criteria:

Level Criteria Strong All services via URL/connection string in config, swappable without code changes Partial Most services configurable but some hardcoded defaults Weak Hardcoded service locations, different code paths per environment

Anti-patterns:

Hardcoded localhost for services in production code Conditional logic for local vs cloud services (if USE_S3: ... else: local_storage) Service-specific code paths based on environment Different drivers for dev vs prod Factor V: Build, Release, Run

Principle: Strictly separate build and run stages.

Search Patterns:

Build/deploy configuration

find . -name "Dockerfile" -o -name "Makefile" -o -name "build.sh" -o -name "deploy.sh" find . -name ".github/workflows/*.yml" -o -name ".gitlab-ci.yml" -o -name "Jenkinsfile"

Build scripts in package.json

grep -A5 '"scripts"' package.json 2>/dev/null | grep -E "build|start|deploy"

Check for runtime compilation (anti-pattern)

grep -r "compile|transpile|webpack" --include="*.py" | grep -v "test|build"

File Patterns: /Dockerfile, /Makefile, /.github/workflows/, CI/CD configs

Compliance Criteria:

Level Criteria Strong Immutable releases, clear build/release/run stages, unique release IDs Partial Build and run separated but release not immutable Weak Runtime code modifications, asset compilation at startup

Anti-patterns:

Runtime code modifications Asset compilation during application startup Configuration baked into build artifacts No release versioning Factor VI: Processes

Principle: Execute the app as one or more stateless processes.

Search Patterns:

Session storage patterns

grep -r "session|Session" --include=".py" --include=".js" --include="*.ts" | head -20

In-process state (anti-pattern)

grep -r "global.cache|process_local|instance_cache" --include=".py" grep -r "global..=|module.exports.cache" --include=".js" --include="*.ts"

External session stores (good pattern)

grep -r "redis.session|memcached.session|session.redis" --include=".py" --include=".js" --include=".ts"

Sticky session configuration (anti-pattern)

grep -r "sticky.session|session.affinity" --include=".yml" --include=".yaml" --include="*.json"

File Patterns: /middleware/*.py, /session/*.py, server configurations

Compliance Criteria:

Level Criteria Strong Stateless processes, all state in external datastores (Redis, DB) Partial Mostly stateless but some in-process caching Weak Sticky sessions, in-process session storage, shared memory state

Anti-patterns:

In-process session storage (user_sessions = {}) Sticky sessions or session affinity File-based caching between requests Global mutable state shared across requests Factor VII: Port Binding

Principle: Export services via port binding.

Search Patterns:

Self-contained port binding

PORT environment variable

grep -r "PORT|port" --include=".py" --include=".js" --include="*.ts" | grep -i "environ|process.env"

Webserver as dependency

File Patterns: /main.py, /server.py, /app.py, /index.js

Compliance Criteria:

Level Criteria Strong Self-contained app binds to PORT, webserver is a dependency Partial Port binding but not configurable via environment Weak Relies on external webserver container (Apache, Nginx) to provide HTTP

Anti-patterns:

Relying on Apache/Nginx/Tomcat to inject webserver functionality Hardcoded port numbers No PORT environment variable support CGI scripts or server modules Factor VIII: Concurrency

Principle: Scale out via the process model.

Search Patterns:

Process definitions

find . -name "Procfile" -o -name "process.yml" -o -name ".foreman"

Multiple entry points

find . -name "worker.py" -o -name "scheduler.py" -o -name "web.py"

Background job systems

File Patterns: /Procfile, /worker.py, **/scheduler.py, queue configurations

Compliance Criteria:

Level Criteria Strong Explicit process types (web, worker, scheduler), horizontal scaling Partial Multiple process types but not easily scalable Weak Single monolithic process, no separation of concerns

Anti-patterns:

Single process handling all workloads Hard-coded worker counts in code No separation between web and background processes Vertical scaling only (bigger server, not more processes) Factor IX: Disposability

Principle: Maximize robustness with fast startup and graceful shutdown.

Search Patterns:

Signal handlers

grep -r "signal.signal|SIGTERM|SIGINT|atexit" --include=".py" grep -r "process.on.SIGTERM|process.on.SIGINT" --include=".js" --include="*.ts"

Graceful shutdown

grep -r "graceful.shutdown|shutdown_handler|cleanup" --include=".py" --include=".js" --include=".ts"

Startup time

grep -r "startup|initialize|bootstrap" --include=".py" --include=".js" --include="*.ts" | head -20

File Patterns: /main.py, /server.py, lifecycle management code

Compliance Criteria:

Level Criteria Strong Fast startup (<10s), SIGTERM handling, graceful shutdown, jobs returnable to queue Partial Graceful shutdown but slow startup Weak No signal handling, jobs lost on process death, slow startup

Anti-patterns:

No SIGTERM/SIGINT handlers Slow startup (>30 seconds) Jobs lost if process crashes No cleanup on shutdown Factor X: Dev/Prod Parity

Principle: Keep development, staging, and production as similar as possible.

Search Patterns:

Different services per environment (anti-pattern)

grep -r "if.development.sqlite|if.production.postgres" --include=".py" --include=".js" --include=".ts" grep -r "development.SQLite|production.PostgreSQL" --include=".py" --include=".js" --include=".ts"

Docker for parity

find . -name "docker-compose*.yml" -o -name "Dockerfile"

Environment-specific backends

grep -r "USE_LOCAL_|LOCAL_STORAGE|MOCK_" --include=".py" --include=".js" --include="*.ts"

File Patterns: */docker-compose.yml, environment configurations

Compliance Criteria:

Level Criteria Strong Same services everywhere (PostgreSQL in dev and prod), containerized Partial Mostly same but some lightweight dev alternatives Weak SQLite in dev, PostgreSQL in prod; different backing services

Anti-patterns:

SQLite for development, PostgreSQL for production In-memory cache in dev, Redis in prod Different service versions across environments "It works on my machine" issues Factor XI: Logs

Principle: Treat logs as event streams.

Search Patterns:

Stdout logging

grep -r "print(|logging.info|logger.info|console.log" --include=".py" --include=".js" --include="*.ts" | head -20

File-based logging (anti-pattern)

Structured logging

grep -r "structlog|json_logger|pino|winston" --include=".py" --include=".js" --include="*.ts"

File Patterns: /logging.py, /logger.py, logging configurations

Compliance Criteria:

Level Criteria Strong Unbuffered stdout only, structured logging (JSON), no file management Partial Stdout logging but with some file handlers Weak Application writes to log files, manages rotation

Anti-patterns:

Writing logs to files (FileHandler, open('/var/log/app.log')) Log rotation logic in application code Log archival managed by application Buffered logging Factor XII: Admin Processes

Principle: Run admin/management tasks as one-off processes.

Search Patterns:

Management commands

find . -name "manage.py" -o -name "Rakefile" -o -name "artisan" grep -r "@cli.command|@click.command|typer.command" --include="*.py"

Migration scripts

find . -name "migrations" -type d find . -name "migration.py" -o -name "migrate.py"

Admin scripts with proper isolation

grep -r "bundle exec|source.venv|uv run" --include=".sh" --include="Makefile"

File Patterns: /manage.py, /cli.py, /migrations/, admin scripts

Compliance Criteria:

Level Criteria Strong Admin tasks use same dependencies/config, proper isolation, idempotent Partial Admin tasks exist but different setup from app Weak Manual database manipulation, scripts without isolation

Anti-patterns:

Admin scripts not using app's dependency manager Direct SQL manipulation outside of migrations Admin scripts with hardcoded credentials Non-idempotent migrations Output Format Executive Summary Table | Factor | Status | Notes |

|--------|--------|-------|

| I. Codebase | Strong/Partial/Weak | [Key finding] |

| II. Dependencies | Strong/Partial/Weak | [Key finding] |

| III. Config | Strong/Partial/Weak | [Key finding] |

| IV. Backing Services | Strong/Partial/Weak | [Key finding] |

| V. Build/Release/Run | Strong/Partial/Weak | [Key finding] |

| VI. Processes | Strong/Partial/Weak | [Key finding] |

| VII. Port Binding | Strong/Partial/Weak | [Key finding] |

| VIII. Concurrency | Strong/Partial/Weak | [Key finding] |

| IX. Disposability | Strong/Partial/Weak | [Key finding] |

| X. Dev/Prod Parity | Strong/Partial/Weak | [Key finding] |

| XI. Logs | Strong/Partial/Weak | [Key finding] |

| XII. Admin Processes | Strong/Partial/Weak | [Key finding] |

Overall: X Strong, Y Partial, Z Weak

Per-Factor Analysis

For each factor, provide:

Current Implementation

Evidence with file:line references Code snippets showing patterns

Compliance Level

Strong/Partial/Weak with justification

Gaps

What's missing vs. 12-Factor ideal

Recommendations

Actionable improvements with code examples Analysis Workflow

Initial Scan

Run search patterns for all factors Identify key files for each factor Note any existing compliance documentation

Deep Dive (per factor)

Read identified files Evaluate against compliance criteria Document evidence with file paths

Gap Analysis

Compare current vs. 12-Factor ideal Identify anti-patterns present Prioritize by impact

Recommendations

Provide actionable improvements Include before/after code examples Reference best practices

Summary

Compile executive summary table Highlight strengths and critical gaps Suggest priority order for improvements Quick Reference: Compliance Scoring Score Meaning Action Strong Fully implements principle Maintain, minor optimizations Partial Some implementation, significant gaps Planned improvements Weak Minimal or no implementation High priority for roadmap When to Use This Skill Evaluating new SaaS applications Reviewing cloud-native architecture decisions Auditing production applications for scalability Planning migration to cloud platforms Comparing application architectures Preparing for containerization/Kubernetes deployment

12-factor-apps

安装

Check for version control

Check for environment-specific code branches

Python dependency files

JavaScript/TypeScript dependency files

Check for system tool assumptions

Docker/container isolation

Environment variable usage

Hardcoded credentials (anti-pattern)

Environment-specific config files (anti-pattern)

Database URLs in code

Database connection via config

Service initialization

Hardcoded service locations (anti-pattern)

Build/deploy configuration

Build scripts in package.json

Check for runtime compilation (anti-pattern)

Session storage patterns

In-process state (anti-pattern)

External session stores (good pattern)

Sticky session configuration (anti-pattern)

Self-contained port binding

PORT environment variable

Webserver as dependency

Process definitions

Multiple entry points

Background job systems

Signal handlers

Graceful shutdown

Startup time

Different services per environment (anti-pattern)

Docker for parity

Environment-specific backends

Stdout logging

File-based logging (anti-pattern)

Structured logging

Management commands

Migration scripts

Admin scripts with proper isolation

安装

Check for version control

Check for multiple apps sharing codebase

Check for environment-specific code branches

Python dependency files

JavaScript/TypeScript dependency files

Check for system tool assumptions

Docker/container isolation

Environment variable usage

Hardcoded credentials (anti-pattern)

Environment-specific config files (anti-pattern)

Database URLs in code

Database connection via config

Service initialization

Hardcoded service locations (anti-pattern)

Build/deploy configuration

Build scripts in package.json

Check for runtime compilation (anti-pattern)

Session storage patterns

In-process state (anti-pattern)

External session stores (good pattern)

Sticky session configuration (anti-pattern)

Self-contained port binding

PORT environment variable

Webserver as dependency

Process definitions

Multiple entry points

Background job systems

Signal handlers

Graceful shutdown

Startup time

Different services per environment (anti-pattern)

Docker for parity

Environment-specific backends

Stdout logging

File-based logging (anti-pattern)

Structured logging

Management commands

Migration scripts

Admin scripts with proper isolation