Initial commit

2026-05-12 15:40:22 -06:00
parent 5b279865a1
commit 1eac72b3cd
31 changed files with 1192 additions and 45 deletions
@@ -0,0 +1,48 @@
+# 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.