Building Block #09: Redis Caching

Status: 📋 Planned
Dependencies: Building Block #08 (Deployment)
When: Month 2 (after foundation complete)
Context: Solo Developer + AI

Definition

Add Redis caching layer for:

• Permission caching (improve RBAC performance)
• User session data caching
• Frequently accessed data caching
• Cache invalidation patterns

Dependencies

• ✅ Building Block #01-08: Foundation complete
  • Database Setup (#01)
  • Authentication (#02)
  • RBAC Implementation (#03)
  • Multi-Tenancy (#04)
  • API Foundation (#05)
  • Frontend Foundation (#06)
  • AI Service Setup (#07)
  • Deployment (#08)
• Requires Redis 7.x (NOT 8.x)
• Requires ioredis 5.x client

Technology Addition Process

This building block follows the Technology Addition Process:

1. ✅ ADR Created: ADR-010: Add Redis Caching
2. ✅ Building Block Defined: This document
3. ⏳ Complete Through Gates: In progress
4. ⏳ Update Boilerplate: After completion
5. ⏳ Update AI Context: After completion

Implementation Checklist

GATE 1: BUILD

Redis Setup

• Install Redis 7.x locally
• Install ioredis 5.x client
• Configure Redis connection
• Set up connection pooling
• Test Redis connection
• Set up Cloud Memorystore (for production)

Permission Caching

• Create cache service
• Implement permission caching
• Add cache key naming convention
• Implement TTL-based expiration (1 hour)
• Add cache invalidation on role changes
• Test permission caching

Cache Patterns

• Implement TTL-based caching
• Implement event-based invalidation
• Implement pattern-based invalidation
• Implement version-based invalidation
• Test all cache patterns

Integration

• Update permission service to use cache
• Update repositories to use cache (where appropriate)
• Add cache health check
• Test cache integration

GATE 2: TEST

• Test Redis connection
• Test permission caching
• Test cache invalidation
• Test all cache patterns
• Test performance improvements
• Write unit tests for cache service
• Write integration tests for caching
• All tests passing

GATE 3: REVIEW & APPROVE

• Self-review cache implementation
• Verify performance improvements
• Check cache invalidation works
• Review cache key naming
• Document approval reasoning
• Status: ✅ APPROVED

GATE 4: DOCUMENT

• Document Redis setup
• Document cache patterns
• Document cache key naming
• Document invalidation strategies
• Update ADR with implementation details
• Update boilerplate definition (move Redis to "Included")
• Update .cursorrules with Redis patterns
• Update CLAUDE.md with Redis setup
• Update memory log

GATE 5: COMMIT & TAG

• Git commit with clear message: "Building Block #09: Redis Caching complete"
• Tag: building-block-09-redis
• Push to main
• Update status tracker

Testing Requirements

Unit Tests

• Cache service methods
• Cache key generation
• Cache invalidation
• TTL handling

Integration Tests

• Permission caching
• Cache invalidation on role changes
• Performance improvements
• Redis connection

Documentation Requirements

• Redis setup documentation
• Cache patterns guide
• Cache key naming convention
• Invalidation strategies guide
• ADR for Redis caching
• Performance improvements documentation

Approval Criteria

Building block is complete when:

• ✅ Redis integrated
• ✅ Permission caching working
• ✅ Cache invalidation working
• ✅ Performance improved
• ✅ All tests passing
• ✅ Boilerplate updated
• ✅ Documentation complete

AI Context

What AI needs to know:

• Use Redis 7.x (NOT 8.x)
• Use ioredis 5.x client
• Cache permissions with 1-hour TTL
• Invalidate cache on role changes
• Cache key format: permission:{tenantId}:{userId}
• Use TTL-based expiration for most cases

Patterns to follow:

• Cache key format: permission:{tenantId}:{userId}
• Check cache before database query
• Invalidate cache on role/permission changes
• Use TTL-based expiration (1 hour for permissions)

Boilerplate Update

After completion, update Boilerplate Definition:

• Move Redis from "NOT Included" to "Included"
• Update technology list
• Document Redis patterns

Next Building Block

After completion, can proceed to:

• Feature building blocks (Employee Management #11, etc.)
• Building Block #10: BullMQ + Events (Month 4)

---

Last Updated: 2025-11-27