linearvoid/docs/architecture/adr/ADR-007-redis-usage.md

ADR-007: Redis Usage (Where, When, and How) + Admin Configuration Capabilities

Status: Proposed
Date: 2026-08-02
Author: AI Assistant (following AGENTS.md and previous ADRs)
Related ADRs: ADR-001, ADR-003, ADR-005, ADR-006

Context

Redis is planned for several real-time and transient use cases in the chat and playout services. ADR-005 and ADR-006 require that the admin interface be able to view Redis statistics and adjust configuration values (rate limits, TTLs, presence expiry, etc.) with full audit logging.

We must explicitly document:

• Exact use cases for Redis.
• Configuration policies (TTL, persistence, high availability).
• Graceful degradation if Redis is unavailable.
• Admin interface capabilities to inspect and modify Redis settings.

Decision Drivers

1. Performance – Redis is ideal for presence, rate limiting, and pub/sub.
2. Simplicity – Use a single Redis instance initially; document scaling path.
3. Observability – Admin UI must provide real-time visibility and configuration controls.
4. Reliability – Define fallback behavior (e.g., disable rate limiting if Redis is down).
5. Auditability – All configuration changes made via admin UI must be logged.

Decision

Use Redis 7+ as the primary in-memory store with the following defined use cases:

Defined Use Cases:

• Presence: Track online users per room (SET with TTL).
• Rate Limiting: Per-user and per-IP rate limits using Redis INCR + EXPIRE.
• Pub/Sub: Broadcast chat messages and moderation events to connected WebSocket clients.
• Cache: Short-lived cache for playout status and "now playing" metadata (from ADR-001).
• Session Data: Temporary admin session tokens (if not using JWT).

Configuration Policies:

• Default TTL for presence: 60 seconds (refreshed on activity).
• Rate limit windows: 10 requests per 10 seconds per user (configurable via admin UI).
• Persistence: RDB snapshots every 15 minutes + AOF for safety.
• High Availability: Start with single instance; add Sentinel or Cluster in v2.
• Fallback: If Redis is unavailable, disable real-time presence and rate limiting but continue basic chat functionality (with warning in logs and admin UI).

Admin Interface Capabilities (extension of ADR-005):

• Dedicated "Redis Configuration" tab in the admin dashboard.
• View real-time stats: memory usage, connected clients, key counts, hit/miss ratio, slow log.
• Adjustable parameters: rate limit thresholds, presence TTL, cache TTL, pub/sub channel prefixes.
• Actions: Flush specific keys/patterns, trigger save, view slow log, test connectivity.
• All changes are audited to the moderation log (with before/after values) and require confirmation.

Folder Placement (per ADR-002):

• Redis client wrapper in backend/shared/redis/.
• Admin UI components in frontend/admin/system/redis/.
• Configuration defaults in backend/shared/config/redis.go.

Rationale

• Redis is the standard choice for the real-time features required by the chat system (ADR-001).
• Explicit documentation of use cases and fallback behavior prevents misuse.
• Admin interface capabilities fulfill the requirement from the TODO plan and ADR-005, giving operators full control without SSH access.
• Starting simple (single instance) aligns with ADR-003's operational simplicity goal while providing a clear scaling path.

Consequences

Positive:

• Clear, auditable, and configurable Redis usage.
• Admin UI provides powerful observability and tuning without restarting services.
• Graceful degradation path defined.

Negative / Risks:

• Redis becomes a single point of failure for presence and rate limiting (mitigated by fallback logic).
• Memory usage must be monitored (admin UI will surface this).
• Configuration changes via admin UI must be carefully validated to prevent accidental DoS or data loss.

Alternatives Considered:

• No Redis (use only PostgreSQL) – rejected for performance on real-time features.
• Dragonfly or KeyDB – rejected to stay with mature, well-supported Redis.
• In-memory Go maps only – rejected for lack of persistence and cross-process sharing.

Implementation Plan

1. Create this ADR-007 (done).
2. Implement Redis client wrapper with configuration reload support.
3. Build the admin UI tab for Redis stats and configuration (linked to ADR-005).
4. Add fallback logic in chat and playout services when Redis is unavailable.
5. Update docker-compose.yml to include Redis with persistence.
6. Add monitoring (Prometheus exporter) and admin audit logging for configuration changes.
7. Write tests for rate limiting, presence, and admin configuration flows.

References

• ADR-001: Chat features requiring presence, rate limiting, and pub/sub.
• ADR-003: Go preference and operational simplicity.
• ADR-005: Admin interface foundation – this ADR extends it with Redis and storage configuration capabilities.
• ADR-006: Data storage decision (Redis complements the primary SQL store).
• arc42 documentation: Cross-cutting Concepts (caching, monitoring, security) and Deployment View.

This completes the documentation for data storage and caching decisions. All admin capabilities are now traceable before implementation begins.