# CLAUDE.md - Project Guidelines for OTA Micro-Server

## Project Overview
This project is a high-concurrency, low-bandwidth OTA (Over-the-Air) management and distribution server built in Go. It is specifically designed to distribute updates to thousands of devices under a highly constrained network pipelining landscape (**10 Mbps bandwidth ceiling**). It manages binary/Jar delta file generation, gating rollouts, and concurrent rate-limiting.

## Technology Stack
- **Backend Language:** Go (Golang)
- **Database:** PostgreSQL (with migration tool e.g., Flyway/Golang-migrate)
- **Key Algorithms/Protocols:** BSDiff/VCDIFF for delta generation, HTTP Range requests for resumable downloads.
- **Documentation & Code Comments:** Strictly adhere to **British English** spelling conventions (e.g., `colour`, `centre`, `optimise`, `standardisation`).

---

## Build, Test & Run Commands

### Development
- **Run the server:** `go run cmd/server/main.go`
- **Build the binary:** `go build -o bin/ota-server cmd/server/main.go`
- **Format code:** `go fmt ./...`
- **Lint code:** `golangci-lint run`

### Testing
- **Run all tests:** `go test ./...`
- **Run with coverage:** `go test -coverprofile=coverage.out ./...`

---

## Code Architecture & Design Principles

### 1. 10M Bandwidth Strategy (Hard Constraints)
- **Gated Rollout (Token-based):** Devices must acquire a download token before pulling updates. Keep concurrent downloads limited (e.g., max 50 concurrent streams).
- **Rate Limiting:** Implement token bucket or leaky bucket algorithms at the application/middleware layer to throttle download speed per connection.
- **Resumable Downloads:** The download endpoint **must** support HTTP 206 Partial Content and handle `Range` headers properly.

### 2. Jar/Zip Delta Logic
- **Do not perform direct binary diffs on raw `.jar` files.**
- To generate a delta:
    1. Unzip the old Jar and new Jar into isolated temporary directories.
    2. Compare files sequentially. Identify new, deleted, and modified files.
    3. Apply binary diff (like BSDiff) **only** on modified `.class` or resource files.
    4. Packaging: Zip the modified patches, new files, and a `manifest.json` describing the deletion/replacement steps into a final `.patch` package.

### 3. Database & Concurrency
- Optimise SQL queries to prevent connection pooling bottlenecks under thousands of periodic heartbeats/checking requests.
- Use explicit transactions when updating device upgrade status (`Checking` -> `Downloading` -> `Verifying` -> `Upgraded`).

---

## Code Style & Conventions
- **Naming:** Idiomatic Go (camelCase for internal variables, PascalCase for exported identifiers). Short but descriptive context names.
- **Error Handling:** Handle all errors explicitly. Wrap errors with meaningful context using `fmt.Errorf("context: %w", err)`.
- **Concurrency:** Ensure goroutines are safe, utilize `sync.Pool` for heavy allocations (like decompression buffers), and use `context.Context` for cancellation propagation.
- **Spelling:** Always double-check spelling in logs, errors, and variable definition to ensure **British English** alignment (e.g., use `optimised_delta_buffer` instead of `optimized_delta_buffer`).