# Story 1.1: Replace Redis Configuration with Single URL

**Status:** Draft

---

## User Story

As a **developer**,
I want **Redis configuration via a single REDIS_URL environment variable**,
So that **I can easily configure the application for both local development and Azure Redis Cache without splitting connection strings into multiple parts**.

---

## Acceptance Criteria

**Given** the Settings class in src/core/config.py
**When** the application loads configuration from environment
**Then** it uses a single redis_url field instead of 4 individual fields

**And** the redis_url supports both redis:// (non-SSL) and rediss:// (SSL) schemes

**And** Celery connects successfully using settings.redis_url

**And** Progress tracker initializes successfully using settings.redis_url

**And** all existing tests pass without modification to Redis consumers

**And** new unit tests validate direct redis_url field behavior

**And** .env.example shows clear examples for local and Azure configurations

**And** docker-compose.yml uses simplified Redis configuration

---

## Implementation Details

### Tasks / Subtasks

1. **Refactor Settings Class**
   - [ ] Remove redis_host field (src/core/config.py:13)
   - [ ] Remove redis_port field (src/core/config.py:14)
   - [ ] Remove redis_password field (src/core/config.py:15)
   - [ ] Remove redis_db field (src/core/config.py:16)
   - [ ] Add redis_url field: `redis_url: str = "redis://localhost:6379"`
   - [ ] Remove @property redis_url() method (lines 48-59)
   - [ ] Update comment on line 39 (remove old REDIS_URL reference)

2. **Update Environment Template**
   - [ ] Replace Redis configuration block in .env.example (lines 11-20)
   - [ ] Add REDIS_URL with local example: `redis://localhost:6379`
   - [ ] Add REDIS_URL with Azure example: `rediss://:password@cache.redis.cache.windows.net:6380`
   - [ ] Add explanatory comments for both formats

3. **Update Docker Infrastructure**
   - [ ] Simplify Redis service in docker-compose.yml (lines 21-36)
   - [ ] Remove conditional password handling
   - [ ] Update healthcheck if needed
   - [ ] Keep service simple for local development

4. **Update Configuration Tests**
   - [ ] Remove test_redis_url_with_password (tests/core/test_config.py:8-16)
   - [ ] Remove test_redis_url_without_password (lines 19-27)
   - [ ] Remove test_redis_url_custom_database (lines 30-38)
   - [ ] Remove test_redis_url_custom_host_port (lines 41-49)
   - [ ] Remove test_redis_url_no_password_custom_db (lines 52-60)
   - [ ] Add test_redis_url_default() - verify default value
   - [ ] Add test_redis_url_local() - test non-SSL URL with database
   - [ ] Add test_redis_url_azure_ssl() - test SSL URL with password

5. **Update Documentation**
   - [ ] Update Redis configuration section in README.md
   - [ ] Show new REDIS_URL format
   - [ ] Provide both local and Azure examples
   - [ ] Update setup instructions

6. **Verification**
   - [ ] Run unit tests: `pytest tests/core/test_config.py -v`
   - [ ] Run all tests: `pytest`
   - [ ] Start docker-compose: `docker-compose up -d`
   - [ ] Start API: `uvicorn src.api.main:app --reload`
   - [ ] Start worker: `celery -A src.workers.celery_app worker --loglevel=info`
   - [ ] Test health endpoint: `curl http://localhost:8000/health`
   - [ ] Verify Redis connection in logs

### Technical Summary

This story refactors the Redis configuration approach from 4 separate environment variables to a single REDIS_URL, following the same pattern as DATABASE_URL. The change simplifies configuration management and enables direct use of Azure Redis Cache connection strings.

**Key Changes:**
- Settings class: Replace 4 fields + @property with single direct field
- Environment: Single REDIS_URL replaces 4 variables
- No changes to Redis consumers (settings.redis_url remains accessible)
- Tests: Replace property-builder tests with direct-field tests

**Why This Works:**
- Both `redis` and `celery` libraries natively parse URLs
- URL parsing extracts host, port, password, db, and SSL settings
- Supports both `redis://` (non-SSL) and `rediss://` (SSL)
- User provides complete URL including database number if needed

### Project Structure Notes

- **Files to modify:**
  - `src/core/config.py` (Settings class)
  - `.env.example` (environment template)
  - `docker-compose.yml` (Redis service)
  - `tests/core/test_config.py` (configuration tests)
  - `README.md` (documentation)

- **Expected test locations:**
  - Unit tests: `tests/core/test_config.py`
  - Integration tests: `tests/extraction/test_integration.py` (should pass unchanged)
  - Service tests: `tests/services/test_progress_tracker.py` (should pass unchanged)

- **Estimated effort:** 2 story points

- **Prerequisites:** None (standalone change)

### Key Code References

**Settings Class Pattern:**
- See `database_url` field in src/core/config.py:10 - uses same direct URL pattern
- See `sync_database_url` property (lines 43-45) - property used for transformation, not building

**Redis Client Initialization:**
- `redis.asyncio.from_url()` in src/services/progress_tracker.py:37
- Celery broker/backend in src/workers/celery_app.py:59-60

**Existing Test Pattern:**
- tests/core/test_config.py - Create Settings instances with kwargs
- Assert on field values directly

---

## Context References

**Tech-Spec:** [tech-spec-redis-url.md](../tech-spec-redis-url.md) - Primary context document containing:

- Complete brownfield codebase analysis
- Python 3.11 + FastAPI 0.122 stack details
- Redis 5.0+ and Celery 5.3+ integration points
- Existing patterns: Pydantic Settings, black/ruff/mypy
- All file paths, line numbers, and implementation guidance
- Testing strategy with exact test cases
- Deployment and monitoring procedures

**Architecture:** docs/architecture.md (system architecture)

**Previous Redis Work:** docs/tech-spec-redis-auth.md (earlier Redis authentication implementation)

---

## Dev Agent Record

### Agent Model Used

<!-- Will be populated during dev-story execution -->

### Debug Log References

<!-- Will be populated during dev-story execution -->

### Completion Notes

<!-- Will be populated during dev-story execution -->

### Files Modified

<!-- Will be populated during dev-story execution -->

### Test Results

<!-- Will be populated during dev-story execution -->

---

## Review Notes

<!-- Will be populated during code review -->
