Job-List/QUICKSTART_REDIS.md

# Quick Start: Redis/Valkey Caching

## Prerequisites

1. Redis or Valkey server running and accessible
2. PocketBase instance running at `https://pocketbase.ccllc.pro`
3. Bun runtime installed

## Setup Steps

### 1. Configure Environment

Add to your `.env` file (typically at `/home/admin/secrets/.env`):

```bash
# Redis/Valkey - use the same instance as Job-Info-Prod
REDIS_URL=redis://localhost:6379
# Or for production: REDIS_URL=redis://your-redis-server:6379
```

### 2. Install Dependencies

Already installed:
- `ioredis` (^5.8.2)
- `@types/ioredis` (^5.0.0)

### 3. Start the Server

```bash
cd /home/admin/Job-List
bun run dev
```

Server will start on port 3025 with Redis caching enabled.

## Using the API

### Frontend Integration

Update your frontend code to use the new cached endpoints:

#### Fetch All Jobs (Cached)

```javascript
// OLD: Direct PocketBase fetch
const records = await pb.collection('Job_Info_TestEnv').getFullList({
  sort: 'Job_Number',
});

// NEW: Use cached endpoint
const response = await fetch('http://localhost:3025/api/jobs', {
  headers: {
    'X-PocketBase-Token': pb.authStore.token
  }
});
const { data, cached } = await response.json();
console.log(`Data ${cached ? 'from cache' : 'from PocketBase'}`);
```

#### Search Jobs (Cached)

```javascript
// NEW: Search with caching
const searchQuery = 'Estimating';
const response = await fetch(`http://localhost:3025/api/jobs/search?q=${encodeURIComponent(searchQuery)}`, {
  headers: {
    'X-PocketBase-Token': pb.authStore.token
  }
});
const { data, cached, query } = await response.json();
console.log(`Found ${data.length} results for "${query}" ${cached ? '(cached)' : ''}`);
```

#### Clear Cache (Admin Only)

```javascript
const response = await fetch('http://localhost:3025/api/cache/clear', {
  method: 'POST',
  headers: {
    'X-PocketBase-Token': pb.authStore.token
  }
});
const result = await response.json();
console.log(result.message); // "Cache cleared successfully"
```

## Benefits

### Performance Improvements

- **First Request:** ~200-500ms (from PocketBase)
- **Cached Request:** ~5-20ms (from Redis)
- **Speed Improvement:** 10-100x faster for cached requests

### Load Reduction

- Reduces PocketBase queries by ~80-95%
- Allows multiple concurrent users without database strain
- Shared cache across multiple server instances

## Monitoring

### Check Server Logs

Look for these messages:
```
✓ Redis connected successfully
✓ Jobs fetched from cache
✓ Search results fetched from cache
✓ Cache cleared successfully
```

### Monitor Redis

```bash
# Check Redis is running
redis-cli ping

# Monitor all Redis commands in real-time
redis-cli monitor

# Check cache keys
redis-cli keys "jobs:*"
redis-cli keys "search:*"

# Check specific key
redis-cli get "jobs:all:Job_Info_TestEnv"

# Check TTL (time to live) for a key
redis-cli ttl "jobs:all:Job_Info_TestEnv"
```

## Cache Behavior

### Cache TTL (Time To Live)

- **Job Data:** 5 minutes (300 seconds)
- **Search Results:** 3 minutes (180 seconds)

### Cache Invalidation

Automatic invalidation occurs when:
- Data is submitted via `/api/submit`
- Manual cache clear via `/api/cache/clear`

Cache keys invalidated:
- `jobs:*` - All job data caches
- `search:*` - All search result caches

## Troubleshooting

### Problem: "Failed to connect to Redis"

**Solution:**
1. Check Redis is running: `redis-cli ping`
2. Verify `REDIS_URL` in environment
3. Check firewall/network connectivity
4. Try default: `REDIS_URL=redis://localhost:6379`

### Problem: Cache always shows "cached: false"

**Solution:**
1. Check Redis connection is successful
2. Look for connection errors in server logs
3. Verify Redis has enough memory
4. Try clearing cache: `redis-cli FLUSHALL`

### Problem: Seeing stale data

**Solution:**
1. Cache should auto-invalidate on updates
2. Manually clear: `POST /api/cache/clear`
3. Wait for TTL to expire (max 5 minutes)
4. Check update operations use `/api/submit`

## Production Deployment

### Connecting to Job-Info-Prod Redis

Update your production `.env`:

```bash
# Use the same Redis instance as Job-Info-Prod
REDIS_URL=redis://redis-prod-server:6379

# Or with authentication
REDIS_URL=redis://:your-password@redis-prod-server:6379

# Or with TLS
REDIS_URL=rediss://:your-password@redis-prod-server:6379
```

### Security Considerations

1. **Authentication:** Use password-protected Redis in production
2. **Network:** Keep Redis on private network, not public internet
3. **TLS:** Use `rediss://` (Redis with TLS) for encrypted connections
4. **Firewall:** Only allow connections from application servers

### Scaling

Multiple application instances can share the same Redis:
```
┌─────────────┐
│  Instance 1 │───┐
└─────────────┘   │
                  ├───► Redis/Valkey
┌─────────────┐   │
│  Instance 2 │───┤
└─────────────┘   │
                  │
┌─────────────┐   │
│  Instance 3 │───┘
└─────────────┘
```

All instances benefit from shared cache.

## Next Steps

1. ✅ Test caching with `/api/jobs` endpoint
2. ✅ Implement search in frontend using `/api/jobs/search`
3. ✅ Monitor cache hit rates and performance
4. 🔄 Plan migration to Job-Info-Prod for production
5. 🔄 Implement real-time cache updates via Redis PubSub

## Support

For issues or questions:
1. Check server logs for error messages
2. Review [REDIS_IMPLEMENTATION.md](./REDIS_IMPLEMENTATION.md) for detailed documentation
3. Test Redis connection with `redis-cli`
4. Verify environment variables are set correctly