# 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-001.md), [ADR-003](./ADR-003-tech-stack.md), [ADR-005](./ADR-005-admin-moderation-analytics.md), [ADR-006](./ADR-006-data-storage.md)

## 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.