# Racing Scraper - Docker-First Setup Guide

## Complete Setup for Agentic Development with Claude Code

This guide walks you through setting up the racing scraper project with Docker-first architecture and Claude Code for agentic development.

---

## Prerequisites

- Docker and Docker Compose
- Node.js 18+ (for local development)
- Claude Code CLI installed
- Git

---

## Step 1: Initialize the Project

```bash
# Run the initialization script
chmod +x init-project.sh
./init-project.sh

# This creates the racing-scraper/ directory with full structure
cd racing-scraper
```

---

## Step 2: Copy Documentation Files

```bash
# Copy all your documentation to project root
cp /path/to/claude.md .                              # Auto-picked up by Claude Code
cp /path/to/PROJECT_BRIEF.md .                       # Reference documentation
cp /path/to/CLAUDE_CODE_GUIDE.md .                   # Quick reference
cp /path/to/TESTING_OBSERVABILITY_SUMMARY.md .       # Implementation guide

# Copy API specification and examples
cp /path/to/openapi.json .
cp /path/to/list-of-meetings.json .
cp /path/to/specified-meeting.json .
cp /path/to/specified-race.json .
```

**Critical**: `claude.md` at the project root is automatically loaded by Claude Code!

---

## Step 3: Configure Environment

```bash
# Create your .env from the example
cp .env.example .env

# Edit .env with your actual values
vim .env  # or nano, code, etc.
```

**Required variables:**

```bash
TAB_API_BASE_URL=https://api.tab.com.au
TAB_API_KEY=your-actual-api-key

# These are already correct for Docker
DATABASE_URL=postgresql://racing:racing123@postgres:5432/racing_db
REDIS_URL=redis://redis:6379
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318
```

---

## Step 4: Start Docker Services

The project is now **Docker-first**. All services run in containers:

```bash
# Start all infrastructure services
docker-compose up -d postgres redis jaeger prometheus grafana

# Wait for services to be healthy (about 10 seconds)
docker-compose ps

# Verify services are running:
# - postgres: healthy
# - redis: healthy
# - jaeger: running
# - prometheus: running
# - grafana: running
```

### Access the Observability Stack

- **Jaeger UI** (tracing): http://localhost:16686
- **Prometheus** (metrics): http://localhost:9091
- **Grafana** (dashboards): http://localhost:3000 (admin/admin)

---

## Step 5: Start Claude Code for Agentic Development

Now that infrastructure is ready, start Claude Code:

```bash
# From project root (where claude.md is)
claude-code
```

Claude Code will automatically:

1. Read `claude.md` for context, patterns, and priorities
2. Understand the testing/observability requirements
3. Know about the Docker-first architecture

---

## Agentic Development Commands

### Fully Autonomous Mode

Give Claude Code a high-level goal and let it work:

```bash
# In Claude Code prompt:

"Read PROJECT_BRIEF.md. You have full context on this racing scraper project.
Implement Phase 2 (TAB API Client) autonomously following these rules:

1. Write tests FIRST (TDD approach)
2. Target 90%+ test coverage
3. Add comprehensive logging with Pino
4. Add metrics with prom-client
5. Add OpenTelemetry tracing
6. Test against real Docker services (postgres, redis)
7. Verify all tests pass

Work through all tasks in Phase 2. Report back when complete or blocked.
Do NOT ask for permission for standard development tasks."
```

### Progressive Autonomous Mode

Work through phases one at a time:

```bash
"Implement Phase 2 of PROJECT_BRIEF.md autonomously.
Report when complete, then I'll approve Phase 3."
```

### Supervised Autonomous Mode

Let Claude Code work but check in regularly:

```bash
"Work on Phase 2 autonomously. Check in with me after:
1. Writing the test suite
2. Implementing the API client
3. Adding observability

Ask questions if genuinely blocked, but make decisions on implementation details yourself."
```

---

## Development Workflow

### Option A: Run App in Docker (Recommended for Production-Like Testing)

```bash
# Build and start the app container
docker-compose up -d app

# View logs
docker-compose logs -f app

# Run tests in container
docker-compose exec app npm test

# Run specific test suite
docker-compose exec app npm run test:unit
docker-compose exec app npm run test:integration
```

### Option B: Run App Locally (Faster Iteration)

```bash
# Install dependencies locally
npm install

# Generate Prisma client
npm run prisma:generate

# Run migrations (against Docker postgres)
npm run prisma:migrate

# Start dev server with hot reload
npm run dev

# In another terminal, run tests
npm test -- --watch
```

**Note**: Even when running locally, the app connects to Docker services (postgres, redis, jaeger).

---

## Claude Code Working with Docker

Claude Code can interact with your Docker services:

### Running Tests

```typescript
// Claude Code will create tests that use the Docker services
describe("MeetingService Integration", () => {
  // This connects to Docker postgres automatically
  beforeAll(async () => {
    prisma = new PrismaClient();
  });

  it("should store meeting in database", async () => {
    await service.storeMeeting(meeting);
    // Actual database call to Docker postgres
  });
});
```

### Checking Service Health

```bash
# Claude Code can run these commands to verify setup
docker-compose exec postgres pg_isready
docker-compose exec redis redis-cli ping

# Check Prisma connection
npx prisma db pull
```

---

## Observability During Development

### Viewing Traces

1. Make some API calls (via tests or manual)
2. Open Jaeger: http://localhost:16686
3. Select "racing-scraper" service
4. See all traces with spans

### Viewing Metrics

1. Make some operations happen
2. Open Prometheus: http://localhost:9091
3. Query metrics: `api_request_duration_seconds`
4. Or view in Grafana: http://localhost:3000

### Viewing Logs

```bash
# If running in Docker
docker-compose logs -f app

# If running locally
# Logs print to console with pino-pretty formatting
```

---

## Claude Code Best Practices for This Project

### 1. Let It Work Autonomously

```bash
# ❌ Don't micromanage:
"Create the API client file"
"Now add error handling"
"Now add tests"

# ✅ Give high-level goals:
"Implement the complete TAB API client from PROJECT_BRIEF.md Phase 2.
Include tests, logging, metrics, and tracing. Work autonomously."
```

### 2. Trust the Documentation

Claude Code has everything it needs in `claude.md`:

- Code patterns and examples
- Testing requirements
- Observability requirements
- Error handling standards

You don't need to repeat these in prompts.

### 3. Intervene Only When Needed

Let Claude Code work until it:

- Asks a question (genuinely blocked)
- Reports completion
- Encounters an error it can't resolve

### 4. Review Progress in Phases

```bash
"Complete Phase 2, then stop and let me review before Phase 3"
```

---

## Verification Checklist

After Claude Code completes Phase 2, verify:

### Tests

```bash
npm test                    # All tests pass
npm run test:coverage       # Coverage >90%
```

### Code Quality

```bash
npm run lint               # No lint errors
npm run type-check         # No TypeScript errors
```

### Observability

```bash
# Start the app
npm run dev

# Make a test API call
curl http://localhost:8080/health

# Check Jaeger for traces
# Check Prometheus for metrics
# Check logs for structured output
```

### Docker Integration

```bash
docker-compose ps          # All services healthy
npm run prisma:studio      # Can connect to DB
```

---

## Troubleshooting

### Claude Code Can't Find claude.md

```bash
# Verify you're in project root
pwd
# Should show: /path/to/racing-scraper

# Verify file exists
ls -la claude.md

# Restart Claude Code from project root
cd /path/to/racing-scraper
claude-code
```

### Docker Services Not Starting

```bash
# Check Docker is running
docker ps

# Check service logs
docker-compose logs postgres
docker-compose logs redis

# Restart all services
docker-compose down
docker-compose up -d
```

### Tests Can't Connect to Docker Services

```bash
# Verify DATABASE_URL in .env points to localhost:5432
# (Not 'postgres:5432' - that's for containers only)

DATABASE_URL=postgresql://racing:racing123@localhost:5432/racing_db
REDIS_URL=redis://localhost:6379
```

### Claude Code Seems Stuck

```bash
# Check if it's waiting for Docker operations
docker-compose logs -f

# Check if tests are running
ps aux | grep jest

# Give it more specific guidance:
"You seem stuck. Current status? What's blocking you?"
```

---

## Example: Complete Phase 2 Session

Here's a realistic full session:

```bash
# 1. Start infrastructure
docker-compose up -d postgres redis jaeger prometheus grafana

# 2. Start Claude Code
claude-code

# 3. Give autonomous instructions
> "Read PROJECT_BRIEF.md Phase 2. Implement the complete TAB API client
   following TDD principles. Include:
   - Full test suite (unit + integration)
   - 90%+ coverage
   - Comprehensive logging
   - Metrics instrumentation
   - OpenTelemetry tracing

   Use the openapi.json and example JSON files for type definitions.
   Test against Docker services.
   Work autonomously. Report when complete."

# 4. Claude Code works (30-60 minutes)
#    - Creates test files
#    - Implements API client
#    - Adds observability
#    - Runs tests
#    - Fixes issues

# 5. Claude Code reports completion

> "Phase 2 complete. Test coverage: 93%. All tests passing.
   API client ready with:
   - Rate limiting (bottleneck)
   - Retry logic (exponential backoff)
   - Comprehensive error handling
   - Full TypeScript types
   - Structured logging throughout
   - Prometheus metrics
   - OpenTelemetry spans

   Ready for Phase 3?"

# 6. You verify
npm test
npm run test:coverage
# Check Jaeger: http://localhost:16686
# Check Prometheus: http://localhost:9091

# 7. Approve next phase
> "Excellent! Please proceed with Phase 3: Data Services."
```

---

## Next Steps After Setup

1. **Complete Phase 2** (API Client) - 1-2 hours with Claude Code
2. **Complete Phase 3** (Services) - 2-3 hours
3. **Complete Phase 4** (Scheduling) - 2-3 hours
4. **Test Everything** (Phase 5) - 2 hours
5. **Deploy to Production** - 1 hour

Total: ~2-3 days of Claude Code working autonomously with your guidance.

---

## Tips for Maximum Productivity

### 1. Clear the Path

Before starting Claude Code:

- ✅ All Docker services running
- ✅ .env configured
- ✅ All documentation in place

### 2. Trust the Agent

Don't hover. Let Claude Code work for 30-60 minutes, then check progress.

### 3. Batch Your Reviews

Instead of reviewing every file, review at phase completion:

- Run test suite
- Check coverage report
- Review key files
- Approve or request changes

### 4. Use the Observability Stack

Check Jaeger and Prometheus regularly to see the system in action.

### 5. Keep Docker Logs Open

```bash
docker-compose logs -f app
```

Helps you see what Claude Code is doing in real-time.

---

## Summary

**Your Setup:**

- ✅ Docker-first architecture
- ✅ Full observability stack (Jaeger, Prometheus, Grafana)
- ✅ Comprehensive documentation (claude.md auto-loaded)
- ✅ No Sentry (custom error tracking via Postgres)
- ✅ Ready for agentic development

**Start Command:**

```bash
docker-compose up -d
claude-code
# Then give high-level autonomous instructions
```

**Result:**
Production-grade racing scraper built autonomously by Claude Code with comprehensive tests, logging, metrics, and tracing - all verified against real Docker services.

---

_Happy agentic development! 🤖🏇_