From 9a790e1211294fceda62a96077ec7d9a7bee9375 Mon Sep 17 00:00:00 2001
From: siujamo <jamo.siu@gmail.com>
Date: Tue, 7 Jul 2026 10:31:14 +0800
Subject: [PATCH] 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)
---
 CHANGELOG.md    | 21 +++++++++++++++
 CONTRIBUTING.md | 48 ++++++++++++++++++++++++++++++++++
 README.md       | 69 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 138 insertions(+)
 create mode 100644 CHANGELOG.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 README.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..0e0c7ad
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,21 @@
+# Changelog
+
+## [0.1.0] — Unreleased
+
+### Added
+
+- Device registration, heartbeat, and update-check polling API
+- Artefact upload with SHA-256 integrity verification
+- Deployment management with target resolution (all, group, device)
+- Gated rate-limited download endpoint with HTTP Range support
+- JAR delta generation (BSDiff-style binary diff and patch packaging)
+- JWT authentication with admin user CRUD
+- React admin panel (dashboard, versions, deployments, users)
+- PostgreSQL auto-migration and auto-create database
+- OpenAPI 3.0 specification for daemon-facing endpoints
+
+### Changed
+
+- N/A (initial release under active development)
+
+[0.1.0]: https://github.com/onixbyte/pipely/tree/v0.1.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..6102684
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,48 @@
+# Contributing to Pipely
+
+Thank you for your interest in contributing.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone git@onixbyte.dev:<your-org>/pipely.git`
+3. Create a branch: `git switch -c feature/your-feature`
+
+## Development
+
+### Backend (Go)
+
+```bash
+go run cmd/server/main.go      # run the server
+go test ./...                   # run tests
+go vet ./...                    # lint
+```
+
+### Frontend (React)
+
+```bash
+cd web
+pnpm install
+pnpm dev                        # dev server with HMR and API proxy
+pnpm build                      # production build
+```
+
+## Code Style
+
+- **Go**: Standard `gofmt` formatting. Run `go fmt ./...` before committing.
+- **TypeScript**: ESLint + Prettier. Run `pnpm lint` before committing.
+- **Spelling**: British English throughout (e.g. `colour`, `centre`, `optimise`, `artefact`).
+- **Commit messages**: Follow [Conventional Commits](https://www.conventionalcommits.org/).
+
+## Pull Requests
+
+- Keep changes focused and minimal
+- Ensure `go build ./...` and `pnpm build` pass
+- Update documentation if your change affects the API
+
+## Reporting Issues
+
+Use the issue tracker. Include:
+- Steps to reproduce
+- Expected and actual behaviour
+- Environment details (Go version, PostgreSQL version, OS)
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..80f59b7
--- /dev/null
+++ b/README.md
@@ -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