pipely/CLAUDE.md

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).