feat: rebuild work queue api with fastapi and postgres

docs/index.md

@@ -0,0 +1,84 @@
+# Work Queue API
+
+## Overview
+
+A lightweight internal API that tracks the full lifecycle of work items across TheLab agents.
+
+## Quick start
+
+1. Start the stack with Docker Compose.
+2. Wait for PostgreSQL and the API healthcheck to pass.
+3. Call `GET /health`.
+4. Create projects and work items with the API endpoints below.
+
+## Status lifecycle diagram
+
+```text
+queued -> dispatched -> in_progress -> completed
+                               \-> blocked
+                               \-> failed
+queued/dispatched -> cancelled
+```
+
+## API endpoint reference
+
+### Projects
+- `POST /projects`
+- `GET /projects`
+- `GET /projects/{id}`
+- `PATCH /projects/{id}`
+
+### Work
+- `POST /work`
+- `GET /work`
+- `GET /work/{id}`
+- `PATCH /work/{id}`
+- `DELETE /work/{id}`
+
+### Monitoring
+- `GET /work?status=in_progress`
+- `GET /work?status=blocked`
+- `GET /work?status=failed`
+- `GET /work?status=completed&since=<ts>`
+
+## Docker Compose
+
+```yaml
+version: '3.8'
+services:
+  api:
+    image: git.danhenry.dev/thelab/work-queue-api:latest
+    ports:
+      - "8080:8080"
+    environment:
+      - DATABASE_URL=postgresql://postgres:password@db:5432/work_queue
+      - PORT=8080
+    depends_on:
+      db:
+        condition: service_healthy
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      - POSTGRES_PASSWORD=password
+      - POSTGRES_DB=work_queue
+    volumes:
+      - ./data/postgres:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+```
+
+## Notes
+- FastAPI web service
+- PostgreSQL storage
+- No auth
+- One `in_progress` work item per agent is enforced in the database