TemplateDocs
Architecture decision record
An architecture decision record template: the context, options weighed, the decision, its consequences, and when to revisit it.
Last updated
Fill in the blanks
Assembled in your browser — nothing you type is stored or sent anywhere.
Your document
# ADR: Session storage: Redis vs. in-memory
**Status:** Accepted · **Date:** 2026-09-04 · **Author:** Platform team
## Context
Sessions currently live in each app server's memory, which breaks sticky sessions during deploys and blocks horizontal autoscaling. Traffic has grown enough that autoscaling is now blocking the roadmap.
## Options considered
1. Keep in-memory, add sticky sessions at the load balancer - cheap, but caps autoscaling and complicates blue-green deploys.
2. Move sessions to managed Redis - adds one dependency and about $60/month, but removes the stickiness requirement entirely.
3. Move to stateless, token-based sessions - no store needed, but forces a token-revocation redesign we don't have time for this quarter.
## Decision
Move session storage to a managed Redis instance in the same region as the app servers.
## Consequences
Deploys no longer need sticky sessions, which unlocks autoscaling. We accept a new dependency - Redis availability now factors into our uptime - and a small latency cost per request for the network hop.
## Revisit when
Revisit if Redis costs exceed $500/month at current pricing, or if we adopt stateless auth for other reasons.
How to use it well
- →List the options you seriously considered, including the one you're doing today - a decision that never mentions the status quo reads as if no one checked whether change was worth it.
- →Write the consequence you don't like, not just the one you do. An ADR that only lists upside is a pitch deck, and the downside is exactly what the next engineer needs to plan around.
- →The revisit clause is what stops an ADR from calcifying into unquestionable law - give it a concrete trigger (a cost, a metric, a date) rather than "if it stops working."