# CLAUDE.md

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

## Commands

```bash
make build          # Compile Go binary to bin/server
make run            # Build Docker images and start all containers
make run-server     # Build Docker images and start only the Go server
make run-db         # Start only MongoDB container
make run-test       # Run all Go tests
go test ./...       # Run all tests (same as make run-test)
go test ./cmd/server/... -run TestHealth  # Run a single test by name
```

The server listens on `:8080`. MongoDB runs on `27017`. The `MONGO_URI` env var configures the DB connection (default: `mongodb://localhost:27017/logjensticks`).

## Architecture

LogJensticks is a trucking job application management system. The stack is Go + MongoDB, containerized with Docker Compose.

**Current state**: Early skeleton — only `/health` is implemented. The design doc (`DesignDoc`) is the authoritative reference for what needs to be built.

### Code layout

- `cmd/server/` — single Go package containing the HTTP server entry point and all handlers (no separate packages yet)
- `Dockerfile` — multi-stage build: `golang:1.21-alpine` builder → `alpine:latest` final image

### Key design concepts (from DesignDoc)

**Unregistered user flow**: First upload/submit issues a random `unreg_token` stored as a secure, HTTP-only cookie. All subsequent requests use this cookie. A token can only access applications it created. Registration upgrades the session and allows access to prior documents.

**Anti-gaming rule**: Applicants must never see check results, OCR data, or the reason for rejection. Only `correction_feedback` (set by an approver) is shown when an application is returned. Approvers see everything.

**Check pipeline**: On submission, primary checks run immediately in goroutines. Dependent checks launch when their parent check completes. Each check writes `"processing"` → `"pass"` / `"fail"` / `"human_review"` to its named field on the document.

**Application statuses**: `draft` → `submitted` → `processing` → `approved` / `rejected` / `returned` / `human_review`

**Roles**: Unregistered Trucker, Registered Trucker, Approver/Manager, Admin. Role-based access enforced on every protected endpoint.

**API response envelope**:
```json
{"success": true, "data": {...}, "error": null}
{"success": false, "data": null, "error": {"code": "...", "message": "..."}}
```

See `DesignDoc` for the full endpoint list, data schema, OCR job format, and MongoDB index recommendations.