ENGINEERING WIKI LOG TEMPLATE

→ ENTRY STRUCTURE (use for every decision)
  Date: 2025-08-31
  Decision: "Migrate authentication from Session-based to JWT tokens"
  Owner: Engineering lead (who drove the decision)
  Status: IMPLEMENTED
  Impact: Security, Performance, Migration timeline (all systems affected)

→ DECISION CONTENT
  Problem: "Session store Redis becoming bottleneck at 10k concurrent users; scaling costs rising"
  Context: "3-month growth from 2k to 10k users; current SLA at 99.5% availability"
  Options considered:
    1. Scale Redis vertically (cost: $15k/month additional) – REJECTED (diminishing returns)
    2. Implement JWT + refresh tokens (cost: $5k engineering, 6 weeks) – CHOSEN
    3. Stay session-based + shard storage (cost: $8k, 4 weeks, ongoing complexity) – REJECTED
  Decision rationale: "JWT eliminates session state dependency; enables edge caching; reduces operational overhead"
  
→ RESOLUTION & ROLLBACK PLAN
  Implementation path: Phase 1 (new users JWT, 2 weeks) → Phase 2 (migrate existing, 3 weeks) → Phase 3 (deprecate Session, 1 week)
  Rollback: If JWT verification hits >0.5% failure rate during Phase 1, revert to Session for that cohort
  Metrics tracked: Auth latency, token validation errors, user session churn

→ OUTCOME (updated post-implementation)
  Launched: Sept 15, 2025
  Actual impact: Auth latency reduced 30% (target: 25%); no issues in Phase 1; full migration on track
  Lessons: Rate-limiting token refresh calls discovered late – added to future auth decisions
  Related decisions: See JWT Secret Rotation (Decision #47), Cache Strategy (Decision #51)

→ ARCHIVAL & LINKING
  Link from: Architecture Guide, Authentication section
  Link from: Performance Improvements 2025, page 3
  Archive rule: Keep for 2 years minimum (reference for new team members)
  Trap: Don't archive decisions that become "standard practice" without noting the evolution