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

Factor	Principle	Key Concept
I. Codebase	One codebase, many deploys	Single repo per app, version controlled
II. Dependencies	Explicitly declare and isolate	No implicit system-wide packages
III. Config	Store in environment	Never hardcode configuration
IV. Backing Services	Treat as attached resources	Databases, caches are swappable resources
V. Build, Release, Run	Strict separation	Immutable releases, no runtime changes
VI. Processes	Stateless and share-nothing	Horizontal scaling, no sticky sessions
VII. Port Binding	Export via port	Self-contained, no runtime injection
VIII. Concurrency	Scale out via process model	Horizontal over vertical scaling
IX. Disposability	Fast startup, graceful shutdown	Maximise robustness
X. Dev/Prod Parity	Keep environments similar	Continuous deployment
XI. Logs	Treat as event streams	Separate generation from processing
XII. Admin Processes	Run as one-off processes	Same environment as app
XIII. API First	Design contracts first	Enable parallel development
XIV. Telemetry	Monitor everything	APM, health checks, domain metrics
XV. Security	Authentication & Authorisation	RBAC, identity per request

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/