Fifteen-Factor App Methodology

Overview

The Fifteen-Factor App methodology extends the original Twelve-Factor App principles (created by Heroku in 2012) with three additional factors essential for modern cloud-native applications: API First, Telemetry, and Security.

This methodology provides architectural principles and guidelines for building software-as-a-service applications that are:

• Performant – Optimised for speed and efficiency
• Scalable – Designed for horizontal scaling without significant changes
• Manageable – Easy to deploy, monitor, and maintain
• Resilient – Robust against failures with graceful degradation

When to Apply This Methodology

Apply the Fifteen-Factor principles during:

1. Architecture Planning – When designing new applications or microservices
2. PRP/PRD Creation – When documenting technical requirements and specifications
3. Code Reviews – When evaluating whether implementations follow best practices
4. Migration Planning – When modernising legacy applications for cloud deployment
5. Technical Debt Assessment – When identifying architectural improvements

The Fifteen Factors at a Glance

Applying Factors in Planning Sessions

When creating a PRP, PRD, or architecture plan, evaluate the design against each factor:

Foundation Factors (I-VI)

These establish the baseline for any cloud-native application:

• Codebase: Define repository structure and branching strategy
• Dependencies: Specify package manager and dependency isolation approach
• Config: Plan environment variable strategy and secrets management
• Backing Services: Identify all external services and abstraction layers
• Build/Release/Run: Design CI/CD pipeline with immutable artifacts
• Processes: Ensure stateless design, plan session/state storage

Operational Factors (VII-XII)

These ensure smooth operation and maintenance:

• Port Binding: Define service exposure strategy
• Concurrency: Plan horizontal scaling approach
• Disposability: Design for container orchestration
• Dev/Prod Parity: Minimise environment differences
• Logs: Plan logging infrastructure (ELK, Fluentd, etc.)
• Admin Processes: Automate one-off tasks

Modern Extensions (XIII-XV)

These address contemporary requirements:

• API First: Define OpenAPI/Swagger contracts before implementation
• Telemetry: Plan APM, health endpoints, and observability
• Security: Design authentication/authorisation (OAuth2, RBAC)

Architecture Checklist

Use this checklist when reviewing or planning an application:

□ Single codebase in version control
□ All dependencies explicitly declared
□ Configuration externalised to environment
□ Backing services abstracted and swappable
□ Build, release, run stages separated
□ Stateless processes (no sticky sessions)
□ Services self-contained with port binding
□ Designed for horizontal scaling
□ Fast startup and graceful shutdown
□ Dev/staging/prod environments aligned
□ Logs streamed to external aggregator
□ Admin tasks automated and reproducible
□ API contracts defined before implementation
□ Telemetry: APM, health checks, metrics
□ Security: Authentication and authorisation

Resources

Detailed documentation for each factor is available in the references directory:

• references/overview.md – Complete factor summary with diagrams
• references/original-factors.md – Factors I-XII with implementation examples
• references/modern-extensions.md – Factors XIII-XV (API First, Telemetry, Security)
• references/setup-and-tools.md – Tooling recommendations and quick start

To load detailed information about specific factors, read the appropriate reference file. For example, when planning API design, load references/modern-extensions.md for API First guidance.

Searching References

For specific implementation patterns, search the references:

• API contracts: grep -i "swagger\|openapi" references/
• Logging patterns: grep -i "log\|fluentd\|elk" references/
• Security patterns: grep -i "oauth\|rbac\|authentication" references/
• Container patterns: grep -i "docker\|container" references/