.gitea/workflows/check.yml

@@ -0,0 +1,10 @@
+name: check
+on: [push]
+jobs:
+    check:
+        runs-on: ubuntu-latest
+        steps:
+            # actions/checkout v4.2.2, 2026-02-22
+            - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+            - run: docker build .
+            - run: docker build backend/

backend/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 @sneak (https://sneak.berlin)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

backend/README.md

@@ -0,0 +1,70 @@
+netwatch-server is an MIT-licensed Go HTTP backend by
+[@sneak](https://sneak.berlin) that receives telemetry reports from the NetWatch
+SPA and persists them as zstd-compressed JSONL files on disk.
+
+## Getting Started
+
+```bash
+# Build and run locally
+make run
+
+# Run tests, lint, and format check
+make check
+
+# Docker
+docker build -t netwatch-server .
+docker run -p 8080:8080 netwatch-server
+```
+
+## Rationale
+
+The NetWatch frontend collects latency measurements from the browser but has no
+way to persist or aggregate them. This backend provides a minimal
+`POST /api/v1/reports` endpoint that buffers incoming reports in memory and
+flushes them to compressed files on disk for later analysis.
+
+## Design
+
+The server is structured as an `fx`-wired Go application under `cmd/netwatch-server/`.
+Internal packages in `internal/` follow standard Go project layout:
+
+- **`config`**: Loads configuration from environment variables and config files
+  via Viper.
+- **`handlers`**: HTTP request handlers for the API (health check, report
+  ingestion).
+- **`reportbuf`**: In-memory buffer that accumulates JSONL report lines and
+  flushes to zstd-compressed files when the buffer reaches 10 MiB or every 60
+  seconds.
+- **`server`**: Chi-based HTTP server with middleware wiring and route
+  registration.
+- **`healthcheck`**, **`middleware`**, **`logger`**, **`globals`**: Supporting
+  infrastructure.
+
+### Configuration
+
+| Variable   | Default            | Description                       |
+| ---------- | ------------------ | --------------------------------- |
+| `PORT`     | `8080`             | HTTP listen port                  |
+| `DATA_DIR` | `./data/reports`   | Directory for compressed reports  |
+| `DEBUG`    | `false`            | Enable debug logging              |
+
+### Report storage
+
+Reports are written as `reports-<timestamp>.jsonl.zst` files in `DATA_DIR`.
+Each file contains one JSON object per line, compressed with zstd. Files are
+created with `O_EXCL` to prevent overwrites.
+
+## TODO
+
+- Add integration test that POSTs a report and verifies the compressed output
+- Add report decompression/query endpoint
+- Add metrics (Prometheus) for buffer size, flush count, report count
+- Add retention policy to prune old report files
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Author
+
+[@sneak](https://sneak.berlin)