Smithery is now a part of Arcade.dev! Read more in our announcement here
The Fifteen-Factor App methodology for modern cloud-native SaaS applications...
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:
Apply the Fifteen-Factor principles during:
| 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 |
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
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 startRead the appropriate reference file for detailed guidance on specific factors.
