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
INLINECODE0	Root path of the codebase to analyze	Required

Analysis Framework

Factor I: Codebase

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

Search Patterns:
CODEBLOCK0

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:
CODEBLOCK1

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

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:
CODEBLOCK2

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 INLINECODE13
• Environment grouping (if ENV == 'production': ...)
• Secrets committed to version control

---

Factor IV: Backing Services

Principle: Treat backing services as attached resources.

Search Patterns:
CODEBLOCK3

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:
CODEBLOCK4

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:
CODEBLOCK5

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:
CODEBLOCK6

File Patterns: **/main.py, **/server.py, **/app.py, INLINECODE29

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:
CODEBLOCK7

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:
CODEBLOCK8

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:
CODEBLOCK9

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:
CODEBLOCK10

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:
CODEBLOCK11

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

CODEBLOCK12

Per-Factor Analysis

For each factor, provide:

1. 1. Current Implementation

- Evidence with file:line references - Code snippets showing patterns

1. 2. Compliance Level

- Strong/Partial/Weak with justification

1. 3. Gaps

- What's missing vs. 12-Factor ideal

1. 4. Recommendations

- Actionable improvements with code examples

---

Analysis Workflow

1. 1. Initial Scan

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

1. 2. Deep Dive (per factor)

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

1. 3. Gap Analysis

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

1. 4. Recommendations

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

1. 5. 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