# Implementation Tasks: Async Jobs

**Feature:** async-jobs
**Status:** approved
**Author:** Claude
**Created:** 2026-02-05

## Task List

### Task 1: Create Redis Queue Package
**ID:** task-1-redis-queue-pkg
**Status:** pending
**Blocked By:** none

Create the shared `pkg/redisqueue` package with job queue abstractions.

**Files to create:**
- `pkg/redisqueue/job.go` - Job struct and JobStatus constants
- `pkg/redisqueue/queue.go` - RedisQueue implementation

**Acceptance Criteria:**
- Job struct with ID, Type, Payload, Status, timestamps
- JobStatus constants: pending, running, completed, failed
- Enqueue: store job data + push ID to queue
- Dequeue: BLPOP queue + fetch job data + set running
- GetJob: fetch job by ID
- UpdateStatus: update job status fields

---

### Task 2: Add Redis Configuration to API Service
**ID:** task-2-api-redis-config
**Status:** pending
**Blocked By:** task-1-redis-queue-pkg

Add Redis URL configuration and client initialization to the API service.

**Files to modify:**
- `services/api/internal/config/config.go` - Add RedisURL field
- `services/api/cmd/server/main.go` - Initialize Redis client

**Acceptance Criteria:**
- Config loads REDIS_URL from environment
- Redis client created in main.go
- Graceful handling of connection errors

---

### Task 3: Implement Job Port and Service
**ID:** task-3-job-service
**Status:** pending
**Blocked By:** task-2-api-redis-config

Create the job port interface and service layer for job operations.

**Files to create:**
- `services/api/internal/port/job.go` - JobQueue interface
- `services/api/internal/service/job.go` - JobService implementation

**Acceptance Criteria:**
- JobQueue interface defines Create and Get operations
- JobService implements business logic
- Service validates input before queue operations

---

### Task 4: Implement Job HTTP Handlers
**ID:** task-4-job-handlers
**Status:** pending
**Blocked By:** task-3-job-service

Create HTTP handlers for POST /jobs and GET /jobs/{id}.

**Files to create:**
- `services/api/internal/api/handlers/job.go` - Job handlers
- `services/api/internal/api/handlers/job_test.go` - Handler tests

**Files to modify:**
- `services/api/internal/api/routes.go` - Register routes

**Acceptance Criteria:**
- POST /api/api/jobs creates job, returns 201
- GET /api/api/jobs/{id} returns job status
- GET /api/api/jobs/{id} returns 404 for unknown
- Request validation with proper error messages
- Tests cover success and error cases

---

### Task 5: Add Redis Configuration to Worker
**ID:** task-5-worker-redis-config
**Status:** pending
**Blocked By:** task-1-redis-queue-pkg

Add Redis URL and job simulation configuration to the worker.

**Files to modify:**
- `workers/background-processor/internal/config/config.go` - Add Redis and simulation config

**Acceptance Criteria:**
- Config loads REDIS_URL from environment
- Config loads JOB_SIMULATION_DURATION with default (2s)

---

### Task 6: Implement Worker Job Processing
**ID:** task-6-worker-job-processing
**Status:** pending
**Blocked By:** task-5-worker-redis-config

Implement the async job handler in the background worker.

**Files to create:**
- `workers/background-processor/internal/handlers/jobs.go` - Job processor

**Files to modify:**
- `workers/background-processor/cmd/worker/main.go` - Register job handler

**Acceptance Criteria:**
- Worker dequeues jobs from Redis
- Worker simulates work with configurable delay
- Worker updates job status to completed
- Worker handles errors and marks jobs failed
- Graceful shutdown waits for in-flight jobs

---

## Dependency Graph

```
task-1-redis-queue-pkg
       │
       ├───────────────────┐
       ▼                   ▼
task-2-api-redis-config   task-5-worker-redis-config
       │                   │
       ▼                   ▼
task-3-job-service        task-6-worker-job-processing
       │
       ▼
task-4-job-handlers
```

## Implementation Order

1. task-1-redis-queue-pkg (no dependencies)
2. task-2-api-redis-config (depends on 1)
3. task-5-worker-redis-config (depends on 1, can run in parallel with 2)
4. task-3-job-service (depends on 2)
5. task-4-job-handlers (depends on 3)
6. task-6-worker-job-processing (depends on 5)