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 |
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/
1---2name: fifteen-factor-app-23description: This skill should be used when planning SaaS application architecture, creating PRPs or PRDs, designing cloud-native applications, evaluating application designs against best practices, or discussing microservices architecture. Provides the Fifteen-Factor App methodology - an extension of the original Twelve-Factor App principles with three additional factors for modern cloud-native applications (API First, Telemetry, Security). Trigger when users mention "fifteen factor", "12 factor", "SaaS architecture", "cloud-native design", "application architecture", "microservices best practices", or are in a planning/architecture session.4metadata:5 source: https://skillmd.com/skills/majiayu000/fifteen-factor-app-26---78# Fifteen-Factor App Methodology910## Overview1112The 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.1314This methodology provides architectural principles and guidelines for building software-as-a-service applications that are:1516- **Performant** - Optimised for speed and efficiency17- **Scalable** - Designed for horizontal scaling without significant changes18- **Manageable** - Easy to deploy, monitor, and maintain19- **Resilient** - Robust against failures with graceful degradation2021## When to Apply This Methodology2223Apply the Fifteen-Factor principles during:24251. **Architecture Planning** - When designing new applications or microservices262. **PRP/PRD Creation** - When documenting technical requirements and specifications273. **Code Reviews** - When evaluating whether implementations follow best practices284. **Migration Planning** - When modernising legacy applications for cloud deployment295. **Technical Debt Assessment** - When identifying architectural improvements3031## The Fifteen Factors at a Glance3233| Factor | Principle | Key Concept |34|--------|-----------|-------------|35| I. Codebase | One codebase, many deploys | Single repo per app, version controlled |36| II. Dependencies | Explicitly declare and isolate | No implicit system-wide packages |37| III. Config | Store in environment | Never hardcode configuration |38| IV. Backing Services | Treat as attached resources | Databases, caches are swappable resources |39| V. Build, Release, Run | Strict separation | Immutable releases, no runtime changes |40| VI. Processes | Stateless and share-nothing | Horizontal scaling, no sticky sessions |41| VII. Port Binding | Export via port | Self-contained, no runtime injection |42| VIII. Concurrency | Scale out via process model | Horizontal over vertical scaling |43| IX. Disposability | Fast startup, graceful shutdown | Maximise robustness |44| X. Dev/Prod Parity | Keep environments similar | Continuous deployment |45| XI. Logs | Treat as event streams | Separate generation from processing |46| XII. Admin Processes | Run as one-off processes | Same environment as app |47| **XIII. API First** | Design contracts first | Enable parallel development |48| **XIV. Telemetry** | Monitor everything | APM, health checks, domain metrics |49| **XV. Security** | Authentication & Authorisation | RBAC, identity per request |5051## Applying Factors in Planning Sessions5253When creating a PRP, PRD, or architecture plan, evaluate the design against each factor:5455### Foundation Factors (I-VI)5657These establish the baseline for any cloud-native application:5859- **Codebase**: Define repository structure and branching strategy60- **Dependencies**: Specify package manager and dependency isolation approach61- **Config**: Plan environment variable strategy and secrets management62- **Backing Services**: Identify all external services and abstraction layers63- **Build/Release/Run**: Design CI/CD pipeline with immutable artifacts64- **Processes**: Ensure stateless design, plan session/state storage6566### Operational Factors (VII-XII)6768These ensure smooth operation and maintenance:6970- **Port Binding**: Define service exposure strategy71- **Concurrency**: Plan horizontal scaling approach72- **Disposability**: Design for container orchestration73- **Dev/Prod Parity**: Minimise environment differences74- **Logs**: Plan logging infrastructure (ELK, Fluentd, etc.)75- **Admin Processes**: Automate one-off tasks7677### Modern Extensions (XIII-XV)7879These address contemporary requirements:8081- **API First**: Define OpenAPI/Swagger contracts before implementation82- **Telemetry**: Plan APM, health endpoints, and observability83- **Security**: Design authentication/authorisation (OAuth2, RBAC)8485## Architecture Checklist8687Use this checklist when reviewing or planning an application:8889```90□ Single codebase in version control91□ All dependencies explicitly declared92□ Configuration externalised to environment93□ Backing services abstracted and swappable94□ Build, release, run stages separated95□ Stateless processes (no sticky sessions)96□ Services self-contained with port binding97□ Designed for horizontal scaling98□ Fast startup and graceful shutdown99□ Dev/staging/prod environments aligned100□ Logs streamed to external aggregator101□ Admin tasks automated and reproducible102□ API contracts defined before implementation103□ Telemetry: APM, health checks, metrics104□ Security: Authentication and authorisation105```106107## Resources108109Detailed documentation for each factor is available in the references directory:110111- `references/overview.md` - Complete factor summary with diagrams112- `references/original-factors.md` - Factors I-XII with implementation examples113- `references/modern-extensions.md` - Factors XIII-XV (API First, Telemetry, Security)114- `references/setup-and-tools.md` - Tooling recommendations and quick start115116To 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.117118### Searching References119120For specific implementation patterns, search the references:121122- API contracts: `grep -i "swagger\|openapi" references/`123- Logging patterns: `grep -i "log\|fluentd\|elk" references/`124- Security patterns: `grep -i "oauth\|rbac\|authentication" references/`125- Container patterns: `grep -i "docker\|container" references/`