name

fifteen-factor-app

description

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.

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/