···1819# Logging level
20RUST_LOG=debug
21+22+# Redis configuration (optional - if not set, falls back to in-memory cache)
23+REDIS_URL=redis://localhost:6379
24+REDIS_TTL_SECONDS=3600
···85 stable pagination
86- **OAuth DPoP authentication** integrated with AIP server for ATProto
87 authentication
008889### Module Organization
90···95- `src/jetstream.rs` - Real-time event processing from ATProto firehose
96- `src/sync.rs` - Bulk synchronization operations with ATProto relay
97- `src/auth.rs` - OAuth verification and DPoP authentication setup
0098- `src/errors.rs` - Error type definitions (reference for new errors)
99100## Error Handling
···131132- After updating, run `cargo check` to fix errors and warnings
133- Don't use dead code, if it's not used remove it
000000000000000000000000000000000000000
···85 stable pagination
86- **OAuth DPoP authentication** integrated with AIP server for ATProto
87 authentication
88+- **Multi-tier caching** with Redis (if configured) or in-memory fallback for
89+ performance optimization
9091### Module Organization
92···97- `src/jetstream.rs` - Real-time event processing from ATProto firehose
98- `src/sync.rs` - Bulk synchronization operations with ATProto relay
99- `src/auth.rs` - OAuth verification and DPoP authentication setup
100+- `src/cache.rs` - Generic caching interface and in-memory cache implementation
101+- `src/redis_cache.rs` - Redis cache implementation for distributed caching
102- `src/errors.rs` - Error type definitions (reference for new errors)
103104## Error Handling
···135136- After updating, run `cargo check` to fix errors and warnings
137- Don't use dead code, if it's not used remove it
138+139+## Caching Architecture
140+141+The application uses a flexible caching system that supports both Redis and in-memory caching with automatic fallback.
142+143+### Cache Configuration
144+145+Configure caching via environment variables:
146+147+```bash
148+# Redis configuration (optional)
149+REDIS_URL=redis://localhost:6379
150+REDIS_TTL_SECONDS=3600
151+```
152+153+If `REDIS_URL` is not set, the application automatically falls back to in-memory caching.
154+155+### Cache Types and TTLs
156+157+- **Actor Cache** (Jetstream): No TTL (permanent cache for slice actors)
158+- **Lexicon Cache**: 2 hours (7200s) - lexicons change infrequently
159+- **Domain Cache**: 4 hours (14400s) - slice domain mappings rarely change
160+- **Collections Cache**: 2 hours (7200s) - slice collections change infrequently
161+- **Auth Cache**: 5 minutes (300s) - OAuth tokens and AT Protocol sessions
162+- **DID Resolution Cache**: 24 hours (86400s) - DID documents change rarely
163+164+### Cache Implementation
165+166+- `src/cache.rs` - Defines the `Cache` trait and `SliceCache` wrapper with domain-specific methods
167+- `src/redis_cache.rs` - Redis implementation of the `Cache` trait
168+- Both implementations provide the same interface through `SliceCache`
169+- Cache keys use prefixed formats (e.g., `actor:{did}:{slice_uri}`, `oauth_userinfo:{token}`)
170+171+### Cache Usage Patterns
172+173+- **Jetstream Consumer**: Creates 4 separate cache instances for actors, lexicons, domains, and collections
174+- **Auth System**: Uses dedicated auth cache for OAuth and AT Protocol session caching
175+- **Actor Resolution**: Caches DID resolution results to avoid repeated lookups
176+- **Automatic Fallback**: Redis failures automatically fall back to in-memory caching without errors