CLAUDE.md

Rama main · réplica de lectura del repositorio original.

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Rules

- **Never run Git commands on the user's behalf.** Do not commit, push, stage, stash, reset, checkout, or otherwise modify repository state via `git`. Read-only inspection (`git status`, `git diff`, `git log`) is fine. Leave all version-control actions to the user.

## Development Commands

### Core Commands
```bash
# Build the application
go build -o forq

# Run the application (requires FORQ_AUTH_SECRET environment variable)
FORQ_AUTH_SECRET=your-secret-token ./forq

# Run database migrations
go run main.go  # migrations run automatically on startup

# Run tests
go test ./...

# Run benchmarks
cd benchmarks && go test -bench=.
```

### Documentation Sites

The project includes two separate Hugo sites:

```bash
# Landing site (marketing)
cd site && npm run dev          # Development server at http://localhost:1313
cd site && npm run build        # Production build
cd site && npm run clean        # Clean build artifacts

# Documentation site (technical docs)
cd docs && npm run dev          # Development server
cd docs && npm run build        # Production build
cd docs && npm run clean        # Clean build artifacts
```

### Platform Support

**Production**: Linux binaries (optimized for performance)
**Development**: Docker available for all platforms
**Other platforms**: Build from source with `go build`

### Docker
```bash
docker run -d \
  --name forq \
  --restart unless-stopped \
  -e FORQ_AUTH_SECRET=your-auth-secret-min-32-chars-long \
  -e FORQ_DB_PATH=/app/data/forq/forq.db \
  -e FORQ_API_ADDR=0.0.0.0:8080 \
  -e FORQ_UI_ADDR=0.0.0.0:8081 \
  -p 8080:8080 \
  -p 8081:8081 \
  -v ~/forq-data:/app/data/forq \
  mykonordy/forq:latest
```

**For Docker, these env vars must be set:**
- `FORQ_DB_PATH` - Sets explicit database location inside container
- `FORQ_API_ADDR=0.0.0.0:8080` - Binds API to all interfaces (required for Docker port mapping)
- `FORQ_UI_ADDR=0.0.0.0:8081` - Binds UI to all interfaces (required for Docker port mapping)

## Architecture Overview

### Core Components
- **`main.go`**: Application entry point, configuration, and startup
- **`api/`**: JSON REST API endpoints for message operations
- **`ui/`**: HTMX-based web interface for queue management
- **`services/`**: Business logic (messages, queues, sessions, monitoring)
- **`db/`**: SQLite repository and database models
- **`common/`**: Shared models, requests, responses, and constants
- **`jobs/`**: Background tasks (cleanup, metrics collection)
- **`metrics/`**: Prometheus metrics integration (optional)

### Database Design
Uses a single SQLite table (`messages`) for both regular queues and dead letter queues (DLQ). Key design decisions:
- WAL mode enabled for better concurrency
- Integer timestamps (milliseconds) for performance
- UUID v7 for message IDs
- Status codes: 0=ready, 1=processing, 2=failed
- DLQ messages identified by `is_dlq` boolean and queue name suffix `-dlq`

### Configuration
All configuration via environment variables:
- **Required**: `FORQ_AUTH_SECRET` (authentication token), `FORQ_DB_PATH` (SQLite database file path)
- **Optional**: `FORQ_ENV` (local|pro), `FORQ_METRICS_ENABLED` (true|false), `FORQ_API_ADDR`, `FORQ_UI_ADDR`, `FORQ_QUEUE_TTL_HOURS`, `FORQ_DLQ_TTL_HOURS`

### Key Design Principles
- Single binary deployment with embedded SQLite
- HTTP/2 preferred for optimal long polling performance
- Simple authentication (single token for all operations)
- Opinionated choices to avoid feature creep
- 256KB message size limit to encourage good architecture
- 5-attempt retry with exponential backoff (1s, 5s, 15s, 30s, 60s)

### API Structure
- **JSON API** (`/api/v1/*`): Programmatic access for producers/consumers
- **HTMX UI** (`/*`): Human-friendly queue management interface
- Two separate servers: API (port 8080) and UI (port 8081) by default

### Message Processing Flow
1. Messages sent to queue via `POST /api/v1/queues/{queue}/messages`
2. Consumers poll via `GET /api/v1/queues/{queue}/messages` (30s long polling); the response includes an opaque delivery `receipt`
3. Processing acknowledgment via `POST /api/v1/queues/{queue}/messages/{messageId}/ack` with the receipt echoed in the `X-Forq-Receipt` header (same for nack); the receipt fences ack/nack to that exact delivery
4. Failed messages retry with exponential backoff, eventually moved to DLQ
5. Background jobs handle cleanup of expired messages and timeout detection

### Metrics (Optional)
When `FORQ_METRICS_ENABLED=true`:
- Prometheus-format metrics at `GET /metrics`
- Separate authentication via `FORQ_METRICS_AUTH_SECRET`
- Real-time API counters and periodic queue depth gauges
- Zero impact on write performance