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:
- Architecture Planning - When designing new applications or microservices
- PRP/PRD Creation - When documenting technical requirements and specifications
- Code Reviews - When evaluating whether implementations follow best practices
- Migration Planning - When modernising legacy applications for cloud deployment
- 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 |
Architecture Checklist
When creating a PRP, PRD, or architecture plan, evaluate the design against each factor. Use this checklist for quick validation:
□ 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 diagramsreferences/original-factors.md - Factors I-XII with implementation examplesreferences/modern-extensions.md - Factors XIII-XV (API First, Telemetry, Security)references/setup-and-tools.md - Tooling recommendations and quick start
Read the appropriate reference file for detailed guidance on specific factors.
1---2name: fifteen-factor-app3description: Cloud-native SaaS architecture methodology extending Twelve-Factor with three additional factors (API First, Telemetry, Security). Use when planning SaaS tools, product software architecture, microservices design, PRPs/PRDs, or cloud-native application development; when the user says "fifteen factor", "12 factor", "SaaS architecture", "cloud-native design", "application architecture", "microservices best practices"; or when in a planning/architecture session. Do NOT use for greenfield monolith design without cloud-native constraints, internal tooling that will never ship as a service, or local-only scripts.4---56# Fifteen-Factor App Methodology78## Overview910The 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.1112This methodology provides architectural principles and guidelines for building software-as-a-service applications that are:1314- **Performant** - Optimised for speed and efficiency15- **Scalable** - Designed for horizontal scaling without significant changes16- **Manageable** - Easy to deploy, monitor, and maintain17- **Resilient** - Robust against failures with graceful degradation1819## When to Apply This Methodology2021Apply the Fifteen-Factor principles during:22231. **Architecture Planning** - When designing new applications or microservices242. **PRP/PRD Creation** - When documenting technical requirements and specifications253. **Code Reviews** - When evaluating whether implementations follow best practices264. **Migration Planning** - When modernising legacy applications for cloud deployment275. **Technical Debt Assessment** - When identifying architectural improvements2829## The Fifteen Factors at a Glance3031| Factor | Principle | Key Concept |32|--------|-----------|-------------|33| I. Codebase | One codebase, many deploys | Single repo per app, version controlled |34| II. Dependencies | Explicitly declare and isolate | No implicit system-wide packages |35| III. Config | Store in environment | Never hardcode configuration |36| IV. Backing Services | Treat as attached resources | Databases, caches are swappable resources |37| V. Build, Release, Run | Strict separation | Immutable releases, no runtime changes |38| VI. Processes | Stateless and share-nothing | Horizontal scaling, no sticky sessions |39| VII. Port Binding | Export via port | Self-contained, no runtime injection |40| VIII. Concurrency | Scale out via process model | Horizontal over vertical scaling |41| IX. Disposability | Fast startup, graceful shutdown | Maximise robustness |42| X. Dev/Prod Parity | Keep environments similar | Continuous deployment |43| XI. Logs | Treat as event streams | Separate generation from processing |44| XII. Admin Processes | Run as one-off processes | Same environment as app |45| **XIII. API First** | Design contracts first | Enable parallel development |46| **XIV. Telemetry** | Monitor everything | APM, health checks, domain metrics |47| **XV. Security** | Authentication & Authorisation | RBAC, identity per request |4849## Architecture Checklist5051When creating a PRP, PRD, or architecture plan, evaluate the design against each factor. Use this checklist for quick validation:5253```54□ Single codebase in version control55□ All dependencies explicitly declared56□ Configuration externalised to environment57□ Backing services abstracted and swappable58□ Build, release, run stages separated59□ Stateless processes (no sticky sessions)60□ Services self-contained with port binding61□ Designed for horizontal scaling62□ Fast startup and graceful shutdown63□ Dev/staging/prod environments aligned64□ Logs streamed to external aggregator65□ Admin tasks automated and reproducible66□ API contracts defined before implementation67□ Telemetry: APM, health checks, metrics68□ Security: Authentication and authorisation69```7071## Resources7273Detailed documentation for each factor is available in the references directory:7475- `references/overview.md` - Complete factor summary with diagrams76- `references/original-factors.md` - Factors I-XII with implementation examples77- `references/modern-extensions.md` - Factors XIII-XV (API First, Telemetry, Security)78- `references/setup-and-tools.md` - Tooling recommendations and quick start7980Read the appropriate reference file for detailed guidance on specific factors.
henkisdabro