docs: add README, CONTRIBUTING, and CHANGELOG

- README with project overview, architecture diagram, and quick start - CONTRIBUTING with development setup and code style guidelines - CHANGELOG starting at 0.1.0 (unreleased, under active development)
2026-07-07 10:31:14 +08:00
parent e070a3fb5f
commit 9a790e1211
3 changed files with 138 additions and 0 deletions
@@ -0,0 +1,69 @@
+# Pipely
+
+High-concurrency, low-bandwidth OTA (Over-the-Air) update management and distribution server built in Go. Designed to distribute updates to thousands of devices under constrained network conditions (**10 Mbps** bandwidth ceiling).
+
+## Features
+
+- **Device Management** — Registration, heartbeat tracking, and online/offline detection
+- **Artefact Versioning** — Upload and manage update packages with SHA-256 integrity verification
+- **Delta Updates** — BSDiff-style binary diffs for JAR files to minimise bandwidth
+- **Gated Rollout** — Token-based concurrency control prevents network saturation
+- **Resumable Downloads** — HTTP Range support (`206 Partial Content`) for interrupted transfers
+- **Per-Connection Throttling** — Token-bucket rate limiting keeps total bandwidth under 10 Mbps
+- **JWT Authentication** — Secure admin API with configurable token expiry
+- **Web Admin Panel** — React-based dashboard for version uploads, deployment management, and user administration
+
+## Architecture
+
+```
+daemon (mcd)                    Pipely Server                  Admin Browser
+    │                                │                              │
+    ├─ POST /devices/register ──────>│                              │
+    ├─ POST /devices/heartbeat ─────>│                              │
+    ├─ GET  /devices/check-update ──>│                              │
+    ├─ GET  /packages/download/:id ─>│  (rate-limited + gated)      │
+    ├─ POST /deployments/:id/status >│                              │
+    │                                │<── JWT login ────────────────┤
+    │                                │<── CRUD artefacts/deployments┤
+```
+
+## Quick Start
+
+### Prerequisites
+
+- Go 1.26+
+- PostgreSQL 16+
+- pnpm (for building the admin panel)
+
+### Running
+
+```bash
+# Clone
+git clone git@onixbyte.dev:onixbyte/pipely.git
+cd pipely
+
+# Configure (copy and edit)
+cp .env.example .env
+
+# Build the admin panel
+cd web && pnpm install && pnpm build && cd ..
+
+# Run
+go run cmd/server/main.go
+```
+
+The server starts on `:8080` by default. The admin panel is served at `/`.
+
+Default login: **admin** / **admin**
+
+### Environment Variables
+
+See `.env.example` for all configuration options with descriptions and examples.
+
+## API
+
+The daemon-facing API is documented in `docs/daemon-api.yaml` (OpenAPI 3.0).
+
+## Licence
+
+TBD