Redis & State Management
Relevant source files
The following files were used as context for generating this wiki page:
The Recoup API utilizes a hybrid state management architecture where transient, operational state is handled by Redis, while persistent, relational data is managed via Supabase. Redis serves as the backbone for background job orchestration, task queuing, and real-time thread state for external platform integrations.
This dual-layer approach ensures that high-velocity state changes (like job status or active chat runs) are processed with low latency, while long-term conversation history and account metadata remain durable and searchable in the primary database.
Sources: README.md:104-106, dev/API-AGENT.md:23-32
Redis Architecture & Infrastructure
Redis is integrated into the system primarily through the ioredis client and supporting specialized libraries for queue and chat state management.
Background Job Queuing
The system implements BullMQ for managing background jobs. This allows the API to offload long-running tasks, such as social media scraping or AI content generation, to worker processes without blocking the main request-response cycle.
- Client:
ioredisis the underlying driver. - Queue Manager:
bullmqhandles the job lifecycle and concurrency.
Sources: package.json:44, package.json:54, dev/API-AGENT.md:29
Chat SDK State Adapter
For external platform integrations (e.g., Slack, GitHub), the system uses the Chat SDK with a dedicated Redis state adapter. This stores transient metadata associated with active communication threads.
- Managed State: Thread status, Run IDs, and associated Pull Request (PR) references.
- Adapter:
@chat-adapter/state-ioredis.
Sources: package.json:41, README.md:104-106
System State Overview
The following diagram illustrates how different types of state are routed between Redis and Supabase.
The diagram shows the distribution of state: short-lived operational data flows through Redis, while historical and relational data is committed to Supabase.
Sources: README.md:95-106, dev/API-AGENT.md:37-60, features/feature-email-client.md:30-45
Persistent State Management (Supabase)
While Redis handles the "live" state of tasks, Supabase acts as the system of record. All domain-specific state transitions must follow strict architectural guidelines.
State Entities
| Entity | Storage Type | Description |
|---|---|---|
| Accounts | Supabase | Root entity for individuals, artists, and organizations. |
| Rooms | Supabase | Logical containers for conversation threads. |
| Memories | Supabase | Individual messages within a room, including user and assistant roles. |
| Job Queues | Redis | Pending and active background tasks (e.g., content generation). |
| Thread Context | Redis | Temporary mapping of Slack/External IDs to internal state. |
Sources: CLAUDE.md:144-149, features/feature-email-client.md:65-70, dev/API-AGENT.md:29
Database Operations Pattern
To maintain state consistency, the project enforces a pattern where database calls are isolated within lib/supabase/[table_name]/. This prevents direct client instantiation in domain logic and ensures consistent state transitions.
// lib/supabase/[table_name]/[action][TableName].ts
import supabase from "@/lib/supabase/serverClient";
export async function selectTableName({ filter }: { filter?: string }) {
let query = supabase.from("table_name").select("*");
// ... execution and error handling
}
Sources: CLAUDE.md:62-92
State Flow in External Integrations
External platforms utilize Redis to maintain context between asynchronous events. A prominent example is the Slack adapter flow.
Redis acts as the intermediary to link original Slack events with asynchronous callbacks from background task runners.
Sources: README.md:95-106
Configuration & Dependencies
The following table summarizes the key software components involved in state management.
| Package | Version | Purpose |
|---|---|---|
ioredis | ^5.8.2 | Primary Redis client for Node.js. |
bullmq | ^5.65.1 | Message queue for background job state. |
@chat-adapter/state-ioredis | ^4.15.0 | Redis adapter for the Chat SDK. |
@supabase/supabase-js | ^2.86.0 | Client for persistent relational state. |
Sources: package.json:41-54
Summary
The state management strategy in the Recoup API is designed for scalability and durability. By offloading volatile data (queues and thread context) to Redis, the system achieves the performance required for real-time interactions and background processing. Simultaneously, by centralizing business-critical data (accounts, rooms, and memories) in Supabase through isolated database functions, the project ensures data integrity and a consistent history for users across all interfaces.