scripts-to-rule-them-all (#10)

Reviewed-on: #10
Co-authored-by: sneak <sneak@sneak.berlin>
Co-committed-by: sneak <sneak@sneak.berlin>

.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: script/cibuild
+            - run: docker build -f Dockerfile.backend .

.prettierignore

@@ -1,3 +1,4 @@
+backend/
 dist/
 node_modules/
 yarn.lock

Dockerfile.backend

@@ -0,0 +1,25 @@
+# golang:1.25-alpine (2026-02-27)
+FROM golang:1.25-alpine@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced AS builder
+
+RUN apk add --no-cache git make gcc musl-dev
+
+# golangci-lint v2.7.2 (2026-02-27)
+RUN CGO_ENABLED=0 go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@9f61b0f53f80672872fced07b6874397c3ed197b
+
+WORKDIR /repo/backend
+COPY backend/go.mod backend/go.sum ./
+RUN go mod download
+COPY .git /repo/.git
+COPY backend/ .
+
+RUN make check
+RUN make build
+
+# alpine:3.23 (2026-02-27)
+FROM alpine:3.23@sha256:25109184c71bdad752c8312a8623239686a9a2071e8825f20acb8f2198c3f659
+
+RUN apk add --no-cache ca-certificates
+COPY --from=builder /repo/backend/netwatch-server /usr/local/bin/netwatch-server
+
+EXPOSE 8080
+ENTRYPOINT ["netwatch-server"]

Makefile

@@ -1,21 +1,35 @@
-.PHONY: dev test lint fmt fmt-check check docker
+.PHONY: bootstrap setup dev test lint fmt fmt-check check docker hooks
+
+# Standard targets are thin shims; the implementations live in script/
+# per the scripts-to-rule-them-all pattern (see the Entrypoints section
+# of README.md).
+
+bootstrap:
+	@script/bootstrap
+
+setup:
+	@script/setup
 
 dev:
 	yarn dev
 
 test:
-	timeout 30 yarn build
+	@script/test
 
 lint:
-	yarn prettier --check .
+	@script/lint
 
 fmt:
-	yarn prettier --write .
+	@script/fmt
 
 fmt-check:
-	yarn prettier --check .
+	@script/fmt-check
 
-check: test lint fmt-check
+check:
+	@script/check
 
 docker:
-	timeout 300 docker build -t netwatch .
+	@script/docker
+
+hooks:
+	@script/install-precommit

README.md

@@ -23,6 +23,29 @@ docker build -t netwatch .
 docker run -p 8080:8080 netwatch
 ```
 
+## Entrypoints
+
+This repository adheres to the
+[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+standard: normalized scripts in `script/` are the entrypoints for the
+development workflow, and the Makefile targets are thin shims that call them. We
+provide:
+
+- `script/bootstrap` — install all dependencies (pinned node via nvm if needed,
+  yarn via corepack, `yarn install --frozen-lockfile`)
+- `script/setup` — make a fresh clone ready for development: bootstrap plus the
+  git pre-commit hook
+- `script/projectname` — print the project name (used for the Docker image tag)
+- `script/test` — run the production build as the test (no unit tests yet)
+- `script/lint` — run prettier in check mode
+- `script/fmt` — format all files (writes)
+- `script/fmt-check` — check formatting (read-only)
+- `script/check` — run test, lint, and fmt-check
+- `script/docker` — build the Docker image tagged via `script/projectname`
+- `script/cibuild` — CI entrypoint: plain `docker build .`
+- `script/precommit` — run by the git pre-commit hook; runs `script/check`
+- `script/install-precommit` — install the git pre-commit hook
+
 ## Rationale
 
 When debugging network issues, it's useful to have a persistent at-a-glance view

REPO_POLICIES.md

@@ -1,108 +1,408 @@
-# Development Policies
+---
+title: Repository Policies
+last_modified: 2026-07-06
+---
 
-- Docker image references by tag are server-mutable, therefore using them is an
+This document covers repository structure, tooling, and workflow standards. Code
-  RCE vulnerability. All docker image references must use cryptographic hashes
+style conventions are in separate documents:
-  to securely specify the exact image that is expected.
 
-- Correspondingly, `go install` commands using things like '@latest' are also
+- [Code Styleguide](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE.md)
-  dangerous RCE. Whenever writing scripts or tools, ALWAYS specify go install
+  (general, bash, Docker)
-  targets using commit hashes which are cryptographically secure.
+- [Go](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_GO.md)
+- [JavaScript](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_JS.md)
+- [Python](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_PYTHON.md)
+- [Go HTTP Server Conventions](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/GO_HTTP_SERVER_CONVENTIONS.md)
 
-- Every repo with software in it must have a Makefile in the root. Each such
+---
-  Makefile should support `make test` (runs the project-specific tests),
-  `make lint`, `make fmt` (writes), `make fmt-check` (readonly), and
-  `make check` (has `test`, `lint`, and `fmt-check` as prereqs), `make docker`
-  (builds docker image).
 
-- Every repo should have a Dockerfile. If the repo contains non-server software,
+- Cross-project documentation (such as this file) must include
-  the Dockerfile should bring up a development environment and `make check`
+  `last_modified: YYYY-MM-DD` in the YAML front matter so it can be kept in sync
-  (i.e. the docker build should fail if the branch is not green).
+  with the authoritative source as policies evolve.
 
-- Platform-specific standard formatting should be used. `black` for python,
+- **ALL external references must be pinned by cryptographic hash.** This
-  `prettier` for js/css/etc, `go fmt` for go. The only changes to default
+  includes Docker base images, Go modules, npm packages, GitHub Actions, and
-  settings should be to specify four-space indents where applicable (i.e.
+  anything else fetched from a remote source. Version tags (`@v4`, `@latest`,
-  everything except `go fmt`).
+  `:3.21`, etc.) are server-mutable and therefore remote code execution
+  vulnerabilities. The ONLY acceptable way to reference an external dependency
+  is by its content hash (Docker `@sha256:...`, Go module hash in `go.sum`, npm
+  integrity hash in lockfile, GitHub Actions `@<commit-sha>`). No exceptions.
+  This also means never `curl | bash` to install tools like pyenv, nvm, rustup,
+  etc. Instead, download a specific release archive from GitHub, verify its hash
+  (hardcoded in the Dockerfile or script), and only then install. Unverified
+  install scripts are arbitrary remote code execution. This is the single most
+  important rule in this document. Double-check every external reference in
+  every file before committing. There are zero exceptions to this rule.
 
-- If local testing is possible (it is not always), `make check` should be a
+- Every repo with software must have a root `Makefile` with these targets:
-  pre-commit hook. If it is not possible, `make lint && make fmt-check` should
+  `make bootstrap`, `make setup`, `make test`, `make lint`, `make fmt` (writes),
-  be a pre-commit hook.
+  `make fmt-check` (read-only), `make check` (runs `test`, `lint`, `fmt-check`),
+  `make docker`, and `make hooks` (installs pre-commit hook). A model Makefile
+  is at `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
 
-- If a working `make test` takes more than 20 seconds, that's a bug that needs
+- Repos follow the
-  fixing. In fact, there should be a timeout specified in the `Makefile` that
+  [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
-  fails it automatically if it takes >30s.
+  pattern: the implementation of each Makefile target lives in an executable
+  script in `script/` (`script/bootstrap`, `script/setup`, `script/test`,
+  `script/lint`, `script/fmt`, `script/fmt-check`, `script/check`,
+  `script/docker`), and the Makefile targets are thin shims that call them. The
+  scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run in
+  minimal containers (e.g. alpine images have no bash); locate the repo root
+  with `$(cd "$(dirname "$0")/.." && pwd -P)` and `cd` there before acting. From
+  the standard's canonical set we use `bootstrap`, `setup` (make the repo ready
+  for development after a fresh clone: runs `bootstrap`, then
+  `install-precommit`, plus any repo-specific initialization), `test`, and
+  `cibuild`. `script/bootstrap` installs all dependencies idempotently and
+  assumes nothing is present: base tools come from nix, apt, brew, or apk
+  (detected in that order; apt runs noninteractive). For node it uses the
+  installed node if present; otherwise it installs a PINNED node version via
+  nvm, first installing nvm itself if missing — from a hash-verified GitHub
+  release archive (never `curl | sh`), with bash installed as an explicit
+  prerequisite since nvm requires bash. yarn is then pinned via
+  `corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
+  always exact versions. `script/cibuild` runs the CI build: it changes to the
+  repo root and runs `docker build .`; the Gitea workflow calls it. Four further
+  scripts are our own extensions to the standard: `script/check` runs
+  `script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
+  what the git pre-commit hook runs, and it calls `script/check`;
+  `script/install-precommit` installs the git pre-commit hook (the `make hooks`
+  target shims to it); and `script/projectname` (literally that filename) simply
+  outputs the project's name. Scripts that need the name call
+  `script/projectname` — e.g. `script/docker` assembles its image tag from it —
+  so those scripts stay byte-identical across all repos. Repo-type-specific
+  pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
+  `script/precommit`, not in the hook itself. Model scripts are at
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
+  must document the provided scripts in an **Entrypoints** section (see the
+  README requirements below).
 
-- Docker builds should time out in 5 minutes or less.
+- Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.)
+  instead of invoking the underlying tools directly. The Makefile is the single
+  source of truth for how these operations are run.
+
+- The Makefile is authoritative documentation for how the repo is used. Beyond
+  the required targets above, it should have targets for every common operation:
+  running a local development server (`make run`, `make dev`), re-initializing
+  or migrating the database (`make db-reset`, `make migrate`), building
+  artifacts (`make build`), generating code, seeding data, or anything else a
+  developer would do regularly. If someone checks out the repo and types
+  `make<tab>`, they should see every meaningful operation available. A new
+  contributor should be able to understand the entire development workflow by
+  reading the Makefile.
+
+- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
+  as a build step so the build fails if the branch is not green. For non-server
+  repos, the Dockerfile should bring up a development environment and run
+  `make check`. For server repos, `make check` should run as an early build
+  stage before the final image is assembled. Dockerfiles install development
+  prerequisites by running `script/bootstrap` rather than duplicating installs
+  inline; COPY `script/` and the dependency manifests (`package.json` +
+  `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
+  layer stays cached until dependencies change.
+
+- **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
+  repos use a multistage build where linting runs in an independent stage based
+  on the `golangci/golangci-lint` image (pinned by hash). This stage runs
+  `make fmt-check` and `make lint` before the full build begins. The build stage
+  then declares an explicit dependency on the lint stage via
+  `COPY --from=lint /src/go.sum /dev/null`, which forces BuildKit to complete
+  linting before proceeding to compilation and tests. This ensures lint failures
+  surface in seconds rather than minutes, without blocking on dependency
+  download or compilation in the build stage.
+
+    The standard pattern for a Go repo Dockerfile is:
+
+    ```dockerfile
+    # Lint stage — fast feedback on formatting and lint issues
+    # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
+    FROM golangci/golangci-lint@sha256:... AS lint
+    WORKDIR /src
+    COPY go.mod go.sum ./
+    RUN go mod download
+    COPY . .
+    RUN make fmt-check
+    RUN make lint
+
+    # Build stage
+    # golang:1.x-alpine, YYYY-MM-DD
+    FROM golang@sha256:... AS builder
+    WORKDIR /src
+
+    # Force BuildKit to run the lint stage before proceeding
+    COPY --from=lint /src/go.sum /dev/null
+
+    COPY go.mod go.sum ./
+    RUN go mod download
+    COPY . .
+    RUN make test
+
+    ARG VERSION=dev
+    RUN CGO_ENABLED=0 go build -trimpath \
+        -ldflags="-s -w -X main.Version=${VERSION}" \
+        -o /app ./cmd/app/
+
+    # Runtime stage
+    FROM alpine@sha256:...
+    COPY --from=builder /app /usr/local/bin/app
+    ENTRYPOINT ["app"]
+    ```
+
+    Key points:
+    - The lint stage uses the `golangci/golangci-lint` image directly (it
+      includes both Go and the linter), so there is no need to install the
+      linter separately.
+    - `COPY --from=lint /src/go.sum /dev/null` is a no-op file copy that creates
+      a stage dependency. BuildKit runs stages in parallel by default; without
+      this line, the build stage would not wait for lint to finish and a lint
+      failure might not fail the overall build.
+    - If the project uses `//go:embed` directives that reference build artifacts
+      (e.g. a web frontend compiled in a separate stage), the lint stage must
+      create placeholder files so the embed directives resolve. Example:
+      `RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`.
+      The lint stage should not depend on the actual build output — it exists to
+      fail fast.
+    - If the project requires CGO or system libraries for linting (e.g.
+      `vips-dev`), install them in the lint stage with `apk add`.
+    - The build stage runs `make test` after compilation setup. Tests run in the
+      build stage, not the lint stage, because they may require compiled
+      artifacts or heavier dependencies.
+
+- Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
+  runs `script/cibuild` (which runs `docker build .`) on push. Since the
+  Dockerfile already runs `make check`, a successful build implies all checks
+  pass.
+
+- Use platform-standard formatters: `black` for Python, `prettier` for
+  JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
+  two exceptions: four-space indents (except Go), and `proseWrap: always` for
+  Markdown (hard-wrap at 80 columns). Documentation and writing repos (Markdown,
+  HTML, CSS) should also have `.prettierrc` and `.prettierignore`.
+
+- Pre-commit hook: runs `script/precommit`, which calls `script/check`. If local
+  testing is not possible in the repo, `script/precommit` may skip `script/test`
+  and run only `script/lint` and `script/fmt-check`. The hook is installed by
+  `script/install-precommit`; the Makefile must provide a `make hooks` target
+  that shims to it.
+
+- All repos with software must have tests that run via the platform-standard
+  test framework (`go test`, `pytest`, `jest`/`vitest`, etc.). If no meaningful
+  tests exist yet, add the most minimal test possible — e.g. importing the
+  module under test to verify it compiles/parses. There is no excuse for
+  `make test` to be a no-op.
+
+- `make test` must complete in under 20 seconds. Add a 30-second timeout in the
+  Makefile.
+
+- **`make test` should use the conditional verbose rerun pattern.** Run tests
+  without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to
+  show full output. This keeps CI logs and `docker build` output clean on
+  success (just package/suite summaries) while providing full diagnostic detail
+  on failure (every test case, every assertion). The general shell pattern:
+
+    ```makefile
+    test:
+    	@<test-command> || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  <test-command-with-v>; exit 1; }
+    ```
+
+    Go example:
+
+    ```makefile
+    test:
+    	@go test -timeout 30s -race -cover ./... || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  go test -timeout 30s -race -v ./...; exit 1; }
+    ```
+
+    Python example:
+
+    ```makefile
+    test:
+    	@python -m pytest || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  python -m pytest -v; exit 1; }
+    ```
+
+    The `exit 1` ensures the target always fails after a rerun — the first run
+    already proved the tests are broken, so the build must not pass even if a
+    flaky test happens to succeed on the second attempt. The rerun exists solely
+    for diagnostic output.
+
+- Docker builds must complete in under 5 minutes.
+
+- `make check` must not modify any files in the repo. Tests may use temporary
+  directories.
 
 - `main` must always pass `make check`, no exceptions.
 
-- Do all changes on a feature branch. You can do whatever you want on a feature
+- Never commit secrets. `.env` files, credentials, API keys, and private keys
-  branch.
+  must be in `.gitignore`. No exceptions.
 
-- We have a standardized `.golangci.yml` which we reuse and is _NEVER_ to be
+- `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
-  modified by an agent, only manually by the user. It can be copied from
+  editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
-  `~/dev/upaas/.golangci.yml` if it exists at that location.
+  Fetch the standard `.gitignore` from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
+  a new repo.
 
-- When specifying images or packages by hash in Dockerfiles or
+- **No build artifacts in version control.** Code-derived data (compiled
-  `docker-compose.yml`, put a comment above the line and show the version and
+  bundles, minified output, generated assets) must never be committed to the
-  date at which it was current.
+  repository if it can be avoided. The build process (e.g. Dockerfile, Makefile)
+  should generate these at build time. Notable exception: Go protobuf generated
+  files (`.pb.go`) ARE committed because repos need to work with `go get`, which
+  downloads code but does not execute code generation.
 
-- For javascript, always use `yarn` over `npm`.
+- Never use `git add -A` or `git add .`. Always stage files explicitly by name.
 
-- Whenever writing dates, ALWAYS write YYYY-MM-DD (ISO 8601).
+- Never force-push to `main`.
 
-- Simple projects should be configured with environment variables, as is
+- Make all changes on a feature branch. You can do whatever you want on a
-  standard for Dockerized applications.
+  feature branch.
 
-- Dockerized web services should listen on the default HTTP port of 8080 unless
+- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
-  overridden with the `PORT` environment variable.
+  manually by the user. Fetch from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`.
 
-- The `README.md` is a project's primary documentation. It should contain at a
+- When pinning images or packages by hash, add a comment above the reference
-  minimum the following sections:
+  with the version and date (YYYY-MM-DD).
-    - Description
-        - Include a short and complete description of the functionality and
-          purpose of the software as the first line in the readme. It must
-          include:
-            - the name
-            - the purpose
-            - the category (web server, SPA, command line tool, etc)
-            - the license
-            - the author
-            - eg: "µPaaS is an MIT-licensed Go web application by @sneak that
-              receives git-frontend webhooks and interacts with a Docker server
-              to build and deploy applications in realtime as certain branches
-              are updated."
-    - Getting Started
-        - a code block with copy-pasteable installation/use sections
-    - Rationale
-        - why does this exist?
-    - Design
-        - how is the program structured?
-    - TODO
-        - This is your TODO list for the project - update it meticulously, even
-          in between commits. Whenever planning, put your todo list in the
-          README so that a separate agent with new context can pick up where you
-          left off.
-    - License
-        - GPL or MIT or WTFPL - ask the user when beginning a new project and
-          include a LICENSE file in the root and in a section in the README.
-    - Author
-        - @sneak (link `@sneak` to `https://sneak.berlin`).
 
-- When beginning a new project, initialize a git repo and make the first commit
+- Use `yarn`, not `npm`.
-  simply the first version of the README.md in the root of the repo.
 
-- For Go packages, the module root is `sneak.berlin/go/...`, such as
+- Write all dates as YYYY-MM-DD (ISO 8601).
-  `sneak.berlin/go/dnswatcher`.
 
-- We use SemVer always.
+- Simple projects should be configured with environment variables.
 
-- If no tag `1.0.0` or greater exists in the repository, modify the existing
+- Dockerized web services listen on port 8080 by default, overridable with
-  migrations and assume no installed base or existing databases. If `>=1.0.0`,
+  `PORT`.
-  database changes add new migration files.
 
-- New repos must have at a minimum the following files:
+- **HTTP/web services must be hardened for production internet exposure before
-    - `README.md`, `.git`, `.gitignore`
+  tagging 1.0.** This means full compliance with security best practices
-    - `POLICIES.md` (copy from `~/Documents/_PROMPTS/POLICIES.md`)
+  including, without limitation, all of the following:
+    - **Security headers** on every response:
+        - `Strict-Transport-Security` (HSTS) with `max-age` of at least one year
+          and `includeSubDomains`.
+        - `Content-Security-Policy` (CSP) with a restrictive default policy
+          (`default-src 'self'` as a baseline, tightened per-resource as
+          needed). Never use `unsafe-inline` or `unsafe-eval` unless
+          unavoidable, and document the reason.
+        - `X-Frame-Options: DENY` (or `SAMEORIGIN` if framing is required).
+          Prefer the `frame-ancestors` CSP directive as the primary control.
+        - `X-Content-Type-Options: nosniff`.
+        - `Referrer-Policy: strict-origin-when-cross-origin` (or stricter).
+        - `Permissions-Policy` restricting access to browser features the
+          application does not use (camera, microphone, geolocation, etc.).
+    - **Request and response limits:**
+        - Maximum request body size enforced on all endpoints (e.g. Go
+          `http.MaxBytesReader`). Choose a sane default per-route; never accept
+          unbounded input.
+        - Maximum response body size where applicable (e.g. paginated APIs).
+        - `ReadTimeout` and `ReadHeaderTimeout` on the `http.Server` to defend
+          against slowloris attacks.
+        - `WriteTimeout` on the `http.Server`.
+        - `IdleTimeout` on the `http.Server`.
+        - Per-handler execution time limits via `context.WithTimeout` or
+          chi/stdlib `middleware.Timeout`.
+    - **Authentication and session security:**
+        - Rate limiting on password-based authentication endpoints. API keys are
+          high-entropy and not susceptible to brute force, so they are exempt.
+        - CSRF tokens on all state-mutating HTML forms. API endpoints
+          authenticated via `Authorization` header (Bearer token, API key) are
+          exempt because the browser does not attach these automatically.
+        - Passwords stored using bcrypt, scrypt, or argon2 — never plain-text,
+          MD5, or SHA.
+        - Session cookies set with `HttpOnly`, `Secure`, and `SameSite=Lax` (or
+          `Strict`) attributes.
+    - **Reverse proxy awareness:**
+        - True client IP detection when behind a reverse proxy
+          (`X-Forwarded-For`, `X-Real-IP`). The application must accept
+          forwarded headers only from a configured set of trusted proxy
+          addresses — never trust `X-Forwarded-For` unconditionally.
+    - **CORS:**
+        - Authenticated endpoints must restrict `Access-Control-Allow-Origin` to
+          an explicit allowlist of known origins. Wildcard (`*`) is acceptable
+          only for public, unauthenticated read-only APIs.
+    - **Error handling:**
+        - Internal errors must never leak stack traces, SQL queries, file paths,
+          or other implementation details to the client. Return generic error
+          messages in production; detailed errors only when `DEBUG` is enabled.
+    - **TLS:**
+        - Services never terminate TLS directly. They are always deployed behind
+          a TLS-terminating reverse proxy. The service itself listens on plain
+          HTTP. However, HSTS headers and `Secure` cookie flags must still be
+          set by the application so that the browser enforces HTTPS end-to-end.
+
+    This list is non-exhaustive. Apply defense-in-depth: if a standard security
+    hardening measure exists for HTTP services and is not listed here, it is
+    still expected. When in doubt, harden.
+
+- `README.md` is the primary documentation. Required sections:
+    - **Description**: First line must include the project name, purpose,
+      category (web server, SPA, CLI tool, etc.), license, and author. Example:
+      "µPaaS is an MIT-licensed Go web application by @sneak that receives
+      git-frontend webhooks and deploys applications via Docker in realtime."
+    - **Getting Started**: Copy-pasteable install/usage code block.
+    - **Entrypoints**: Opens by stating that the repo adheres to the
+      [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+      standard (with that link), then documents each provided `script/`
+      entrypoint and its purpose.
+    - **Rationale**: Why does this exist?
+    - **Design**: How is the program structured?
+    - **TODO**: Update meticulously, even between commits. When planning, put
+      the todo list in the README so a new agent can pick up where the last one
+      left off.
+    - **License**: MIT, GPL, or WTFPL. Ask the user for new projects. Include a
+      `LICENSE` file in the repo root and a License section in the README.
+    - **Author**: [@sneak](https://sneak.berlin).
+
+- First commit of a new repo should contain only `README.md`.
+
+- Go module root: `sneak.berlin/go/<name>`. Always run `go mod tidy` before
+  committing.
+
+- Use SemVer.
+
+- Database migrations live in `internal/db/migrations/` and must be embedded in
+  the binary.
+    - `000_migration.sql` — contains ONLY the creation of the migrations
+      tracking table itself. Nothing else.
+    - `001_schema.sql` — the full application schema.
+    - **Pre-1.0.0:** never add additional migration files (002, 003, etc.).
+      There is no installed base to migrate. Edit `001_schema.sql` directly.
+    - **Post-1.0.0:** add new numbered migration files for each schema change.
+      Never edit existing migrations after release.
+
+- All repos should have an `.editorconfig` enforcing the project's indentation
+  settings.
+
+- Avoid putting files in the repo root unless necessary. Root should contain
+  only project-level config files (`README.md`, `Makefile`, `Dockerfile`,
+  `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
+  language-specific config). Everything else goes in a subdirectory. Canonical
+  subdirectory names:
+    - `bin/` — executable scripts and tools
+    - `cmd/` — Go command entrypoints
+    - `configs/` — configuration templates and examples
+    - `deploy/` — deployment manifests (k8s, compose, terraform)
+    - `docs/` — documentation and markdown (README.md stays in root)
+    - `internal/` — Go internal packages
+    - `internal/db/migrations/` — database migrations
+    - `pkg/` — Go library packages
+    - `share/` — systemd units, data files
+    - `static/` — static assets (images, fonts, etc.)
+    - `web/` — web frontend source
+
+- When setting up a new repo, files from the `prompts` repo may be used as
+  templates. Fetch them from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/<path>`.
+
+- New repos must contain at minimum:
+    - `README.md`, `.git`, `.gitignore`, `.editorconfig`
+    - `LICENSE`, `REPO_POLICIES.md` (copy from the `prompts` repo)
+    - `Makefile`
+    - `script/` entrypoints (`bootstrap`, `setup`, `projectname`, `test`,
+      `lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
+      `install-precommit`)
     - `Dockerfile`, `.dockerignore`
-    - for go: `go.mod`, `go.sum`, `.golangci.yml`
+    - `.gitea/workflows/check.yml`
-    - for js: `package.json`
+    - Go: `go.mod`, `go.sum`, `.golangci.yml`
+    - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
+    - Python: `pyproject.toml`

TODO.md

@@ -1,47 +1,47 @@
 # Workflow
 
-* branch (from `main`)
+- branch (from `main`)
-* do the work in Next Step
+- do the work in Next Step
-* move Next Step to the top of Completed Steps
+- move Next Step to the top of Completed Steps
-* move the top item of Future Steps into Next Step
+- move the top item of Future Steps into Next Step
-* commit (`TODO.md` changes in the same commit as the work)
+- commit (`TODO.md` changes in the same commit as the work)
-* merge to `main` if the branch is not protected, otherwise open a PR
+- merge to `main` if the branch is not protected, otherwise open a PR
-* push
+- push
 
 # Status
 
-pre-1.0. No git tags. Backend work in flight on feat/reportbuf-storage
+pre-1.0. No git tags. Backend work in flight on feat/reportbuf-storage (dirty:
-(dirty: src/main.js). Frontend is functional; backend is new and unmerged.
+src/main.js). Frontend is functional; backend is new and unmerged.
 
 # Next Step
 
-Land feat/reportbuf-storage: finish the in-progress src/main.js change,
+Land feat/reportbuf-storage: finish the in-progress src/main.js change, get make
-get make check green, and merge the branch to main. The branch adds the
+check green, and merge the branch to main. The branch adds the backend (buffered
-backend (buffered zstd-compressed report storage), the CI workflow, and
+zstd-compressed report storage), the CI workflow, and backend repo standard
-backend repo standard files, so merging it also closes most compliance
+files, so merging it also closes most compliance gaps.
-gaps.
 
 # Completed Steps
 
-- 2026-02-27: backend with buffered zstd-compressed report storage; CI
+- 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints, Makefile
-  workflow and backend repo standard files; backend Dockerfile fixed (Go
+  shims, README Entrypoints section
-  1.25, golangci-lint) and moved to repo root (feat/reportbuf-storage,
+- 2026-02-27: backend with buffered zstd-compressed report storage; CI workflow
-  unmerged)
+  and backend repo standard files; backend Dockerfile fixed (Go 1.25,
-- 2026-02-26: host row layout redesigned with CSS grid; overflow and
+  golangci-lint) and moved to repo root (feat/reportbuf-storage, unmerged)
-  spacing fixes; nginx config extracted; port hardcoded to 8080
+- 2026-02-26: host row layout redesigned with CSS grid; overflow and spacing
-- 2026-02-26: debug log panel, median stats, recovery probe, Docker
+  fixes; nginx config extracted; port hardcoded to 8080
-  build fix, S3 Singapore endpoint added
+- 2026-02-26: debug log panel, median stats, recovery probe, Docker build fix,
-- 2026-02-23: summary box redesign, host pinning, local and UTC clocks,
+  S3 Singapore endpoint added
-  checks counter
+- 2026-02-23: summary box redesign, host pinning, local and UTC clocks, checks
-- 2026-02-23: hosts sorted by latency; GET instead of HEAD for latency;
+  counter
-  timeout derived from interval; Hetzner regional endpoints; 3s interval
+- 2026-02-23: hosts sorted by latency; GET instead of HEAD for latency; timeout
+  derived from interval; Hetzner regional endpoints; 3s interval
 - 2026-01-29: initial NetWatch network latency monitor
 
 # Future Steps
 
-- Compliance top-up as one small commit: add .editorconfig and add the
+- Compliance top-up as one small commit: add .editorconfig and add the hooks
-  hooks target to the Makefile
+  target to the Makefile
-- After merge, confirm .gitea/workflows/check.yml is on main and CI is
+- After merge, confirm .gitea/workflows/check.yml is on main and CI is green
-  green (main always green policy)
+  (main always green policy)
-- Decide what to do with untracked resume.sh: commit it, gitignore it,
+- Decide what to do with untracked resume.sh: commit it, gitignore it, or delete
-  or delete it
+  it

backend/.dockerignore

@@ -0,0 +1,2 @@
+node_modules
+.DS_Store

backend/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[Makefile]
+indent_style = tab

backend/.gitignore

@@ -0,0 +1,6 @@
+/netwatch-server
+*.log
+*.out
+*.test
+.env
+data/

backend/.golangci.yml

@@ -0,0 +1,32 @@
+version: "2"
+
+run:
+  timeout: 5m
+  modules-download-mode: readonly
+
+linters:
+  default: all
+  disable:
+    # Genuinely incompatible with project patterns
+    - exhaustruct      # Requires all struct fields
+    - depguard         # Dependency allow/block lists
+    - godot            # Requires comments to end with periods
+    - wsl              # Deprecated, replaced by wsl_v5
+    - wrapcheck        # Too verbose for internal packages
+    - varnamelen       # Short names like db, id are idiomatic Go
+
+linters-settings:
+  lll:
+    line-length: 88
+  funlen:
+    lines: 80
+    statements: 50
+  cyclop:
+    max-complexity: 15
+  dupl:
+    threshold: 100
+
+issues:
+  exclude-use-default: false
+  max-issues-per-linter: 0
+  max-same-issues: 0

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/Makefile

@@ -0,0 +1,53 @@
+UNAME_S := $(shell uname -s)
+VERSION := $(shell git describe --always --dirty)
+BUILDARCH := $(shell uname -m)
+BINARY := netwatch-server
+
+GOLDFLAGS += -X main.Version=$(VERSION)
+GOLDFLAGS += -X main.Buildarch=$(BUILDARCH)
+
+ifeq ($(UNAME_S),Darwin)
+	GOFLAGS := -ldflags "$(GOLDFLAGS)"
+else
+	GOFLAGS = -ldflags "-linkmode external -extldflags -static $(GOLDFLAGS)"
+endif
+
+.PHONY: all build test lint fmt fmt-check check docker hooks run clean
+
+all: build
+
+build: ./$(BINARY)
+
+./$(BINARY): $(shell find . -name '*.go' -type f) go.mod go.sum
+	go build -o $@ $(GOFLAGS) ./cmd/netwatch-server/
+
+test:
+	timeout 30 go test ./...
+
+lint:
+	golangci-lint run ./...
+
+fmt:
+	go fmt ./...
+
+fmt-check:
+	@test -z "$$(gofmt -l .)" || \
+		(echo "Files not formatted:"; gofmt -l .; exit 1)
+
+check: test lint fmt-check
+
+docker:
+	timeout 300 docker build -t netwatch-server -f ../Dockerfile.backend ..
+
+hooks:
+	@printf '#!/bin/sh\ncd backend && make check\n' > \
+		$$(git rev-parse --show-toplevel)/.git/hooks/pre-commit
+	@chmod +x \
+		$$(git rev-parse --show-toplevel)/.git/hooks/pre-commit
+	@echo "Pre-commit hook installed"
+
+run: build
+	./$(BINARY)
+
+clean:
+	rm -f ./$(BINARY)

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)

backend/cmd/netwatch-server/main.go

@@ -0,0 +1,42 @@
+// Package main is the entry point for netwatch-server.
+package main
+
+import (
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/handlers"
+	"sneak.berlin/go/netwatch/internal/healthcheck"
+	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/middleware"
+	"sneak.berlin/go/netwatch/internal/reportbuf"
+	"sneak.berlin/go/netwatch/internal/server"
+
+	"go.uber.org/fx"
+)
+
+//nolint:gochecknoglobals // set via ldflags at build time
+var (
+	Appname   = "netwatch-server"
+	Version   string
+	Buildarch string
+)
+
+func main() {
+	globals.Appname = Appname
+	globals.Version = Version
+	globals.Buildarch = Buildarch
+
+	fx.New(
+		fx.Provide(
+			config.New,
+			globals.New,
+			handlers.New,
+			healthcheck.New,
+			logger.New,
+			middleware.New,
+			reportbuf.New,
+			server.New,
+		),
+		fx.Invoke(func(*server.Server) {}),
+	).Run()
+}

backend/go.mod

@@ -0,0 +1,30 @@
+module sneak.berlin/go/netwatch
+
+go 1.25.5
+
+require (
+	github.com/go-chi/chi/v5 v5.2.5
+	github.com/go-chi/cors v1.2.2
+	github.com/joho/godotenv v1.5.1
+	github.com/klauspost/compress v1.18.4
+	github.com/spf13/viper v1.21.0
+	go.uber.org/fx v1.24.0
+)
+
+require (
+	github.com/fsnotify/fsnotify v1.9.0 // indirect
+	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
+	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/sagikazarmark/locafero v0.11.0 // indirect
+	github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect
+	github.com/spf13/afero v1.15.0 // indirect
+	github.com/spf13/cast v1.10.0 // indirect
+	github.com/spf13/pflag v1.0.10 // indirect
+	github.com/subosito/gotenv v1.6.0 // indirect
+	go.uber.org/dig v1.19.0 // indirect
+	go.uber.org/multierr v1.10.0 // indirect
+	go.uber.org/zap v1.26.0 // indirect
+	go.yaml.in/yaml/v3 v3.0.4 // indirect
+	golang.org/x/sys v0.29.0 // indirect
+	golang.org/x/text v0.28.0 // indirect
+)

backend/go.sum

@@ -0,0 +1,65 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
+github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
+github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
+github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
+github.com/go-chi/chi/v5 v5.2.5 h1:Eg4myHZBjyvJmAFjFvWgrqDTXFyOzjj7YIm3L3mu6Ug=
+github.com/go-chi/chi/v5 v5.2.5/go.mod h1:X7Gx4mteadT3eDOMTsXzmI4/rwUpOwBHLpAfupzFJP0=
+github.com/go-chi/cors v1.2.2 h1:Jmey33TE+b+rB7fT8MUy1u0I4L+NARQlK6LhzKPSyQE=
+github.com/go-chi/cors v1.2.2/go.mod h1:sSbTewc+6wYHBBCW7ytsFSn836hqM7JxpglAy2Vzc58=
+github.com/go-viper/mapstructure/v2 v2.4.0 h1:EBsztssimR/CONLSZZ04E8qAkxNYq4Qp9LvH92wZUgs=
+github.com/go-viper/mapstructure/v2 v2.4.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
+github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
+github.com/klauspost/compress v1.18.4 h1:RPhnKRAQ4Fh8zU2FY/6ZFDwTVTxgJ/EMydqSTzE9a2c=
+github.com/klauspost/compress v1.18.4/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
+github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
+github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/sagikazarmark/locafero v0.11.0 h1:1iurJgmM9G3PA/I+wWYIOw/5SyBtxapeHDcg+AAIFXc=
+github.com/sagikazarmark/locafero v0.11.0/go.mod h1:nVIGvgyzw595SUSUE6tvCp3YYTeHs15MvlmU87WwIik=
+github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 h1:+jumHNA0Wrelhe64i8F6HNlS8pkoyMv5sreGx2Ry5Rw=
+github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8/go.mod h1:3n1Cwaq1E1/1lhQhtRK2ts/ZwZEhjcQeJQ1RuC6Q/8U=
+github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
+github.com/spf13/afero v1.15.0/go.mod h1:NC2ByUVxtQs4b3sIUphxK0NioZnmxgyCrfzeuq8lxMg=
+github.com/spf13/cast v1.10.0 h1:h2x0u2shc1QuLHfxi+cTJvs30+ZAHOGRic8uyGTDWxY=
+github.com/spf13/cast v1.10.0/go.mod h1:jNfB8QC9IA6ZuY2ZjDp0KtFO2LZZlg4S/7bzP6qqeHo=
+github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
+github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/spf13/viper v1.21.0 h1:x5S+0EU27Lbphp4UKm1C+1oQO+rKx36vfCoaVebLFSU=
+github.com/spf13/viper v1.21.0/go.mod h1:P0lhsswPGWD/1lZJ9ny3fYnVqxiegrlNrEmgLjbTCAY=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
+github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
+go.uber.org/dig v1.19.0 h1:BACLhebsYdpQ7IROQ1AGPjrXcP5dF80U3gKoFzbaq/4=
+go.uber.org/dig v1.19.0/go.mod h1:Us0rSJiThwCv2GteUN0Q7OKvU7n5J4dxZ9JKUXozFdE=
+go.uber.org/fx v1.24.0 h1:wE8mruvpg2kiiL1Vqd0CC+tr0/24XIB10Iwp2lLWzkg=
+go.uber.org/fx v1.24.0/go.mod h1:AmDeGyS+ZARGKM4tlH4FY2Jr63VjbEDJHtqXTGP5hbo=
+go.uber.org/goleak v1.2.0 h1:xqgm/S+aQvhWFTtR0XK3Jvg7z8kGV8P4X14IzwN3Eqk=
+go.uber.org/goleak v1.2.0/go.mod h1:XJYK+MuIchqpmGmUSAzotztawfKvYLUIgg7guXrwVUo=
+go.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=
+go.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
+go.uber.org/zap v1.26.0 h1:sI7k6L95XOKS281NhVKOFCUNIvv9e0w4BF8N3u+tCRo=
+go.uber.org/zap v1.26.0/go.mod h1:dtElttAiwGvoJ/vj4IwHBS/gXsEu/pZ50mUIRWuG0so=
+go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+golang.org/x/sys v0.29.0 h1:TPYlXGxvx1MGTn2GiZDhnjPA9wZzZeGKHHmKhHYvgaU=
+golang.org/x/sys v0.29.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/text v0.28.0 h1:rhazDwis8INMIwQ4tpjLDzUhx6RlXqZNPEM0huQojng=
+golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

backend/internal/config/config.go

@@ -0,0 +1,86 @@
+// Package config loads application configuration from
+// environment variables, .env files, and config files.
+package config
+
+import (
+	"errors"
+	"log/slog"
+
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	_ "github.com/joho/godotenv/autoload" // loads .env file
+	"github.com/spf13/viper"
+	"go.uber.org/fx"
+)
+
+// Params defines the dependencies for Config.
+type Params struct {
+	fx.In
+
+	Globals *globals.Globals
+	Logger  *logger.Logger
+}
+
+// Config holds the resolved application configuration.
+type Config struct {
+	DataDir         string
+	Debug           bool
+	MetricsPassword string
+	MetricsUsername string
+	Port            int
+	SentryDSN       string
+	log             *slog.Logger
+	params          *Params
+}
+
+// New loads configuration from env, .env files, and config
+// files, returning a fully resolved Config.
+func New(
+	_ fx.Lifecycle,
+	params Params,
+) (*Config, error) {
+	log := params.Logger.Get()
+	name := params.Globals.Appname
+
+	viper.SetConfigName(name)
+	viper.SetConfigType("yaml")
+	viper.AddConfigPath("/etc/" + name)
+	viper.AddConfigPath("$HOME/.config/" + name)
+
+	viper.AutomaticEnv()
+
+	viper.SetDefault("DATA_DIR", "./data/reports")
+	viper.SetDefault("DEBUG", "false")
+	viper.SetDefault("PORT", "8080")
+	viper.SetDefault("SENTRY_DSN", "")
+	viper.SetDefault("METRICS_USERNAME", "")
+	viper.SetDefault("METRICS_PASSWORD", "")
+
+	err := viper.ReadInConfig()
+	if err != nil {
+		var notFound viper.ConfigFileNotFoundError
+		if !errors.As(err, &notFound) {
+			log.Error("config file malformed", "error", err)
+			panic(err)
+		}
+	}
+
+	s := &Config{
+		DataDir:         viper.GetString("DATA_DIR"),
+		Debug:           viper.GetBool("DEBUG"),
+		MetricsPassword: viper.GetString("METRICS_PASSWORD"),
+		MetricsUsername: viper.GetString("METRICS_USERNAME"),
+		Port:            viper.GetInt("PORT"),
+		SentryDSN:       viper.GetString("SENTRY_DSN"),
+		log:             log,
+		params:          &params,
+	}
+
+	if s.Debug {
+		params.Logger.EnableDebugLogging()
+		s.log = params.Logger.Get()
+	}
+
+	return s, nil
+}

backend/internal/globals/globals.go

@@ -0,0 +1,31 @@
+// Package globals provides build-time variables injected via
+// ldflags and made available through dependency injection.
+package globals
+
+import "go.uber.org/fx"
+
+//nolint:gochecknoglobals // set from main before fx starts
+var (
+	// Appname is the application name.
+	Appname string
+	// Version is the git version tag.
+	Version string
+	// Buildarch is the build architecture.
+	Buildarch string
+)
+
+// Globals holds build-time metadata for the application.
+type Globals struct {
+	Appname   string
+	Version   string
+	Buildarch string
+}
+
+// New creates a Globals instance from package-level variables.
+func New(_ fx.Lifecycle) (*Globals, error) {
+	return &Globals{
+		Appname:   Appname,
+		Buildarch: Buildarch,
+		Version:   Version,
+	}, nil
+}

backend/internal/handlers/handlers.go

@@ -0,0 +1,74 @@
+// Package handlers implements HTTP request handlers for the
+// netwatch-server API.
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/healthcheck"
+	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/reportbuf"
+
+	"go.uber.org/fx"
+)
+
+const jsonContentType = "application/json; charset=utf-8"
+
+// Params defines the dependencies for Handlers.
+type Params struct {
+	fx.In
+
+	Buffer      *reportbuf.Buffer
+	Globals     *globals.Globals
+	Healthcheck *healthcheck.Healthcheck
+	Logger      *logger.Logger
+}
+
+// Handlers provides HTTP handler factories for all endpoints.
+type Handlers struct {
+	buf    *reportbuf.Buffer
+	hc     *healthcheck.Healthcheck
+	log    *slog.Logger
+	params *Params
+}
+
+// New creates a Handlers instance.
+func New(
+	lc fx.Lifecycle,
+	params Params,
+) (*Handlers, error) {
+	s := new(Handlers)
+	s.buf = params.Buffer
+	s.params = &params
+	s.log = params.Logger.Get()
+	s.hc = params.Healthcheck
+
+	lc.Append(fx.Hook{
+		OnStart: func(_ context.Context) error {
+			return nil
+		},
+	})
+
+	return s, nil
+}
+
+func (s *Handlers) respondJSON(
+	w http.ResponseWriter,
+	_ *http.Request,
+	data any,
+	status int,
+) {
+	w.Header().Set("Content-Type", jsonContentType)
+	w.WriteHeader(status)
+
+	if data != nil {
+		err := json.NewEncoder(w).Encode(data)
+		if err != nil {
+			s.log.Error("json encode error", "error", err)
+		}
+	}
+}

backend/internal/handlers/handlers_test.go

@@ -0,0 +1,13 @@
+package handlers_test
+
+import (
+	"testing"
+
+	_ "sneak.berlin/go/netwatch/internal/handlers"
+)
+
+func TestImport(t *testing.T) {
+	t.Parallel()
+	// Compilation check — verifies the package parses
+	// and all imports resolve.
+}

backend/internal/handlers/healthcheck.go

@@ -0,0 +1,11 @@
+package handlers
+
+import "net/http"
+
+// HandleHealthCheck returns a handler for the health check
+// endpoint.
+func (s *Handlers) HandleHealthCheck() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		s.respondJSON(w, r, s.hc.Check(), http.StatusOK)
+	}
+}

backend/internal/handlers/report.go

@@ -0,0 +1,82 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+)
+
+const maxReportBodyBytes = 1 << 20 // 1 MiB
+
+type reportSample struct {
+	T       int64   `json:"t"`
+	Latency *int    `json:"latency"`
+	Error   *string `json:"error"`
+}
+
+type reportHost struct {
+	History []reportSample `json:"history"`
+	Name    string         `json:"name"`
+	Status  string         `json:"status"`
+	URL     string         `json:"url"`
+}
+
+type report struct {
+	ClientID  string          `json:"clientId"`
+	Geo       json.RawMessage `json:"geo"`
+	Hosts     []reportHost    `json:"hosts"`
+	Timestamp string          `json:"timestamp"`
+}
+
+// HandleReport returns a handler that accepts telemetry
+// reports from NetWatch clients.
+func (s *Handlers) HandleReport() http.HandlerFunc {
+	type response struct {
+		Status string `json:"status"`
+	}
+
+	return func(w http.ResponseWriter, r *http.Request) {
+		r.Body = http.MaxBytesReader(
+			w, r.Body, maxReportBodyBytes,
+		)
+
+		var rpt report
+
+		err := json.NewDecoder(r.Body).Decode(&rpt)
+		if err != nil {
+			s.log.Error("failed to decode report",
+				"error", err,
+			)
+			s.respondJSON(w, r,
+				&response{Status: "error"},
+				http.StatusBadRequest,
+			)
+
+			return
+		}
+
+		totalSamples := 0
+		for _, h := range rpt.Hosts {
+			totalSamples += len(h.History)
+		}
+
+		s.log.Info("report received",
+			"client_id", rpt.ClientID,
+			"timestamp", rpt.Timestamp,
+			"host_count", len(rpt.Hosts),
+			"total_samples", totalSamples,
+			"geo", string(rpt.Geo),
+		)
+
+		bufErr := s.buf.Append(rpt)
+		if bufErr != nil {
+			s.log.Error("failed to buffer report",
+				"error", bufErr,
+			)
+		}
+
+		s.respondJSON(w, r,
+			&response{Status: "ok"},
+			http.StatusOK,
+		)
+	}
+}

backend/internal/healthcheck/healthcheck.go

@@ -0,0 +1,82 @@
+// Package healthcheck provides a service that reports
+// application health, uptime, and version information.
+package healthcheck
+
+import (
+	"context"
+	"log/slog"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	"go.uber.org/fx"
+)
+
+// Params defines the dependencies for Healthcheck.
+type Params struct {
+	fx.In
+
+	Config  *config.Config
+	Globals *globals.Globals
+	Logger  *logger.Logger
+}
+
+// Healthcheck tracks startup time and builds health responses.
+type Healthcheck struct {
+	StartupTime time.Time
+	log         *slog.Logger
+	params      *Params
+}
+
+// Response is the JSON payload returned by the health check
+// endpoint.
+type Response struct {
+	Appname       string `json:"appname"`
+	Now           string `json:"now"`
+	Status        string `json:"status"`
+	UptimeHuman   string `json:"uptimeHuman"`
+	UptimeSeconds int64  `json:"uptimeSeconds"`
+	Version       string `json:"version"`
+}
+
+// New creates a Healthcheck, recording startup time via an
+// fx lifecycle hook.
+func New(
+	lc fx.Lifecycle,
+	params Params,
+) (*Healthcheck, error) {
+	s := new(Healthcheck)
+	s.params = &params
+	s.log = params.Logger.Get()
+
+	lc.Append(fx.Hook{
+		OnStart: func(_ context.Context) error {
+			s.StartupTime = time.Now().UTC()
+
+			return nil
+		},
+		OnStop: func(_ context.Context) error {
+			return nil
+		},
+	})
+
+	return s, nil
+}
+
+// Check returns the current health status of the application.
+func (s *Healthcheck) Check() *Response {
+	return &Response{
+		Appname:       s.params.Globals.Appname,
+		Now:           time.Now().UTC().Format(time.RFC3339Nano),
+		Status:        "ok",
+		UptimeHuman:   s.uptime().String(),
+		UptimeSeconds: int64(s.uptime().Seconds()),
+		Version:       s.params.Globals.Version,
+	}
+}
+
+func (s *Healthcheck) uptime() time.Duration {
+	return time.Since(s.StartupTime)
+}

backend/internal/logger/logger.go

@@ -0,0 +1,85 @@
+// Package logger provides a configured slog.Logger with TTY
+// detection for development vs production output.
+package logger
+
+import (
+	"log/slog"
+	"os"
+
+	"sneak.berlin/go/netwatch/internal/globals"
+
+	"go.uber.org/fx"
+)
+
+// Params defines the dependencies for Logger.
+type Params struct {
+	fx.In
+
+	Globals *globals.Globals
+}
+
+// Logger wraps slog.Logger with dynamic level control.
+type Logger struct {
+	log    *slog.Logger
+	level  *slog.LevelVar
+	params Params
+}
+
+// New creates a Logger with TTY-aware output formatting.
+func New(_ fx.Lifecycle, params Params) (*Logger, error) {
+	l := new(Logger)
+	l.level = new(slog.LevelVar)
+	l.level.Set(slog.LevelInfo)
+	l.params = params
+
+	tty := false
+
+	if fileInfo, _ := os.Stdout.Stat(); fileInfo != nil {
+		if (fileInfo.Mode() & os.ModeCharDevice) != 0 {
+			tty = true
+		}
+	}
+
+	var handler slog.Handler
+	if tty {
+		handler = slog.NewTextHandler(
+			os.Stdout,
+			&slog.HandlerOptions{
+				Level:     l.level,
+				AddSource: true,
+			},
+		)
+	} else {
+		handler = slog.NewJSONHandler(
+			os.Stdout,
+			&slog.HandlerOptions{
+				Level:     l.level,
+				AddSource: true,
+			},
+		)
+	}
+
+	l.log = slog.New(handler)
+
+	return l, nil
+}
+
+// EnableDebugLogging sets the log level to debug.
+func (l *Logger) EnableDebugLogging() {
+	l.level.Set(slog.LevelDebug)
+	l.log.Debug("debug logging enabled", "debug", true)
+}
+
+// Get returns the underlying slog.Logger.
+func (l *Logger) Get() *slog.Logger {
+	return l.log
+}
+
+// Identify logs the application's build-time metadata.
+func (l *Logger) Identify() {
+	l.log.Info("starting",
+		"appname", l.params.Globals.Appname,
+		"version", l.params.Globals.Version,
+		"buildarch", l.params.Globals.Buildarch,
+	)
+}

backend/internal/middleware/middleware.go

@@ -0,0 +1,129 @@
+// Package middleware provides HTTP middleware for logging,
+// CORS, and other cross-cutting concerns.
+package middleware
+
+import (
+	"log/slog"
+	"net"
+	"net/http"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	"github.com/go-chi/chi/v5/middleware"
+	"github.com/go-chi/cors"
+	"go.uber.org/fx"
+)
+
+const corsMaxAgeSec = 300
+
+// Params defines the dependencies for Middleware.
+type Params struct {
+	fx.In
+
+	Config  *config.Config
+	Globals *globals.Globals
+	Logger  *logger.Logger
+}
+
+// Middleware holds shared state for middleware factories.
+type Middleware struct {
+	log    *slog.Logger
+	params *Params
+}
+
+// New creates a Middleware instance.
+func New(
+	_ fx.Lifecycle,
+	params Params,
+) (*Middleware, error) {
+	s := new(Middleware)
+	s.params = &params
+	s.log = params.Logger.Get()
+
+	return s, nil
+}
+
+type loggingResponseWriter struct {
+	http.ResponseWriter
+
+	statusCode int
+}
+
+func newLoggingResponseWriter(
+	w http.ResponseWriter,
+) *loggingResponseWriter {
+	return &loggingResponseWriter{w, http.StatusOK}
+}
+
+func (lrw *loggingResponseWriter) WriteHeader(code int) {
+	lrw.statusCode = code
+	lrw.ResponseWriter.WriteHeader(code)
+}
+
+func ipFromHostPort(hostPort string) string {
+	host, _, err := net.SplitHostPort(hostPort)
+	if err != nil {
+		return hostPort
+	}
+
+	return host
+}
+
+// Logging returns middleware that logs each request with
+// timing, status code, and client information.
+func (s *Middleware) Logging() func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(
+			func(w http.ResponseWriter, r *http.Request) {
+				start := time.Now().UTC()
+				lrw := newLoggingResponseWriter(w)
+				ctx := r.Context()
+
+				defer func() {
+					latency := time.Since(start)
+					s.log.InfoContext(ctx, "request",
+						"request_start", start,
+						"method", r.Method,
+						"url", r.URL.String(),
+						"useragent", r.UserAgent(),
+						"request_id",
+						ctx.Value(
+							middleware.RequestIDKey,
+						),
+						"referer", r.Referer(),
+						"proto", r.Proto,
+						"remote_ip",
+						ipFromHostPort(r.RemoteAddr),
+						"status", lrw.statusCode,
+						"latency_ms",
+						latency.Milliseconds(),
+					)
+				}()
+
+				next.ServeHTTP(lrw, r)
+			},
+		)
+	}
+}
+
+// CORS returns middleware that adds permissive CORS headers.
+func (s *Middleware) CORS() func(http.Handler) http.Handler {
+	return cors.Handler(cors.Options{
+		AllowedOrigins: []string{"*"},
+		AllowedMethods: []string{
+			"GET", "POST", "PUT", "DELETE", "OPTIONS",
+		},
+		AllowedHeaders: []string{
+			"Accept",
+			"Authorization",
+			"Content-Type",
+			"X-CSRF-Token",
+		},
+		ExposedHeaders:   []string{"Link"},
+		AllowCredentials: false,
+		MaxAge:           corsMaxAgeSec,
+	})
+}

backend/internal/reportbuf/reportbuf.go

@@ -0,0 +1,199 @@
+// Package reportbuf accumulates telemetry reports in memory
+// and periodically flushes them to zstd-compressed JSONL files.
+package reportbuf
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io/fs"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	"github.com/klauspost/compress/zstd"
+	"go.uber.org/fx"
+)
+
+const (
+	flushSizeThreshold             = 10 << 20 // 10 MiB
+	flushInterval                  = 1 * time.Minute
+	defaultDataDir                 = "./data/reports"
+	dirPerms           fs.FileMode = 0o750
+	filePerms          fs.FileMode = 0o640
+)
+
+// Params defines the dependencies for Buffer.
+type Params struct {
+	fx.In
+
+	Config *config.Config
+	Logger *logger.Logger
+}
+
+// Buffer accumulates JSON lines in memory and flushes them
+// to zstd-compressed files on disk.
+type Buffer struct {
+	buf     bytes.Buffer
+	dataDir string
+	done    chan struct{}
+	log     *slog.Logger
+	mu      sync.Mutex
+}
+
+// New creates a Buffer and registers lifecycle hooks to
+// manage the data directory and flush goroutine.
+func New(
+	lc fx.Lifecycle,
+	params Params,
+) (*Buffer, error) {
+	dir := params.Config.DataDir
+	if dir == "" {
+		dir = defaultDataDir
+	}
+
+	b := &Buffer{
+		dataDir: dir,
+		done:    make(chan struct{}),
+		log:     params.Logger.Get(),
+	}
+
+	lc.Append(fx.Hook{
+		OnStart: func(_ context.Context) error {
+			err := os.MkdirAll(b.dataDir, dirPerms)
+			if err != nil {
+				return fmt.Errorf("create data dir: %w", err)
+			}
+
+			go b.flushLoop()
+
+			return nil
+		},
+		OnStop: func(_ context.Context) error {
+			close(b.done)
+			b.flushLocked()
+
+			return nil
+		},
+	})
+
+	return b, nil
+}
+
+// Append marshals v as a single JSON line and appends it to
+// the buffer. If the buffer reaches the size threshold, it is
+// drained and written to disk asynchronously.
+func (b *Buffer) Append(v any) error {
+	line, err := json.Marshal(v)
+	if err != nil {
+		return fmt.Errorf("marshal report: %w", err)
+	}
+
+	b.mu.Lock()
+	b.buf.Write(line)
+	b.buf.WriteByte('\n')
+
+	if b.buf.Len() >= flushSizeThreshold {
+		data := b.drainBuf()
+		b.mu.Unlock()
+
+		go b.writeFile(data)
+
+		return nil
+	}
+
+	b.mu.Unlock()
+
+	return nil
+}
+
+// flushLoop runs a ticker that periodically flushes buffered
+// data to disk until the done channel is closed.
+func (b *Buffer) flushLoop() {
+	ticker := time.NewTicker(flushInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ticker.C:
+			b.flushLocked()
+		case <-b.done:
+			return
+		}
+	}
+}
+
+// flushLocked acquires the lock, drains the buffer, and
+// writes the data to a compressed file.
+func (b *Buffer) flushLocked() {
+	b.mu.Lock()
+
+	if b.buf.Len() == 0 {
+		b.mu.Unlock()
+
+		return
+	}
+
+	data := b.drainBuf()
+	b.mu.Unlock()
+
+	b.writeFile(data)
+}
+
+// drainBuf copies the buffer contents and resets it.
+// The caller must hold b.mu.
+func (b *Buffer) drainBuf() []byte {
+	data := make([]byte, b.buf.Len())
+	copy(data, b.buf.Bytes())
+	b.buf.Reset()
+
+	return data
+}
+
+// writeFile creates a timestamped zstd-compressed JSONL file
+// in the data directory.
+func (b *Buffer) writeFile(data []byte) {
+	ts := time.Now().UTC().Format("2006-01-02T15-04-05.000Z")
+	name := fmt.Sprintf("reports-%s.jsonl.zst", ts)
+	path := filepath.Join(b.dataDir, name)
+
+	f, err := os.OpenFile( //nolint:gosec // path built from controlled dataDir + timestamp
+		path,
+		os.O_WRONLY|os.O_CREATE|os.O_EXCL,
+		filePerms,
+	)
+	if err != nil {
+		b.log.Error("create report file", "error", err)
+
+		return
+	}
+
+	defer func() { _ = f.Close() }()
+
+	enc, err := zstd.NewWriter(f)
+	if err != nil {
+		b.log.Error("create zstd encoder", "error", err)
+
+		return
+	}
+
+	_, writeErr := enc.Write(data)
+	if writeErr != nil {
+		b.log.Error("write compressed data", "error", writeErr)
+
+		_ = enc.Close()
+
+		return
+	}
+
+	closeErr := enc.Close()
+	if closeErr != nil {
+		b.log.Error("close zstd encoder", "error", closeErr)
+	}
+}

backend/internal/reportbuf/reportbuf_test.go

@@ -0,0 +1,13 @@
+package reportbuf_test
+
+import (
+	"testing"
+
+	_ "sneak.berlin/go/netwatch/internal/reportbuf"
+)
+
+func TestImport(t *testing.T) {
+	t.Parallel()
+	// Compilation check — verifies the package parses
+	// and all imports resolve.
+}

backend/internal/server/http.go

@@ -0,0 +1,43 @@
+package server
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+	"time"
+)
+
+const (
+	readTimeout    = 10 * time.Second
+	writeTimeout   = 10 * time.Second
+	maxHeaderBytes = 1 << 20 // 1 MiB
+)
+
+func (s *Server) serveUntilShutdown() {
+	listenAddr := fmt.Sprintf(":%d", s.params.Config.Port)
+
+	s.httpServer = &http.Server{
+		Addr:           listenAddr,
+		Handler:        s,
+		MaxHeaderBytes: maxHeaderBytes,
+		ReadTimeout:    readTimeout,
+		WriteTimeout:   writeTimeout,
+	}
+
+	s.SetupRoutes()
+
+	s.log.Info("http begin listen",
+		"listenaddr", listenAddr,
+		"version", s.params.Globals.Version,
+		"buildarch", s.params.Globals.Buildarch,
+	)
+
+	err := s.httpServer.ListenAndServe()
+	if err != nil && !errors.Is(err, http.ErrServerClosed) {
+		s.log.Error("listen error", "error", err)
+
+		if s.cancelFunc != nil {
+			s.cancelFunc()
+		}
+	}
+}

backend/internal/server/routes.go

@@ -0,0 +1,31 @@
+package server
+
+import (
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
+)
+
+const requestTimeout = 60 * time.Second
+
+// SetupRoutes configures the chi router with middleware and
+// all application routes.
+func (s *Server) SetupRoutes() {
+	s.router = chi.NewRouter()
+
+	s.router.Use(middleware.Recoverer)
+	s.router.Use(middleware.RequestID)
+	s.router.Use(s.mw.Logging())
+	s.router.Use(s.mw.CORS())
+	s.router.Use(middleware.Timeout(requestTimeout))
+
+	s.router.Get(
+		"/.well-known/healthcheck",
+		s.h.HandleHealthCheck(),
+	)
+
+	s.router.Route("/api/v1", func(r chi.Router) {
+		r.Post("/reports", s.h.HandleReport())
+	})
+}

backend/internal/server/server.go

@@ -0,0 +1,147 @@
+// Package server provides the HTTP server lifecycle,
+// including startup, routing, signal handling, and graceful
+// shutdown.
+package server
+
+import (
+	"context"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/handlers"
+	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/middleware"
+
+	"github.com/go-chi/chi/v5"
+	"go.uber.org/fx"
+)
+
+// Params defines the dependencies for Server.
+type Params struct {
+	fx.In
+
+	Config     *config.Config
+	Globals    *globals.Globals
+	Handlers   *handlers.Handlers
+	Logger     *logger.Logger
+	Middleware *middleware.Middleware
+}
+
+// Server is the top-level HTTP server orchestrator.
+type Server struct {
+	cancelFunc  context.CancelFunc
+	exitCode    int
+	h           *handlers.Handlers
+	httpServer  *http.Server
+	log         *slog.Logger
+	mw          *middleware.Middleware
+	params      Params
+	router      *chi.Mux
+	startupTime time.Time
+}
+
+// New creates a Server and registers lifecycle hooks for
+// starting and stopping it.
+func New(
+	lc fx.Lifecycle,
+	params Params,
+) (*Server, error) {
+	s := new(Server)
+	s.params = params
+	s.mw = params.Middleware
+	s.h = params.Handlers
+	s.log = params.Logger.Get()
+
+	lc.Append(fx.Hook{
+		OnStart: func(_ context.Context) error {
+			s.startupTime = time.Now().UTC()
+
+			go func() { //nolint:contextcheck // fx OnStart ctx is startup-only; run() creates its own
+				s.run()
+			}()
+
+			return nil
+		},
+		OnStop: func(_ context.Context) error {
+			if s.cancelFunc != nil {
+				s.cancelFunc()
+			}
+
+			return nil
+		},
+	})
+
+	return s, nil
+}
+
+// ServeHTTP delegates to the chi router.
+func (s *Server) ServeHTTP(
+	w http.ResponseWriter,
+	r *http.Request,
+) {
+	s.router.ServeHTTP(w, r)
+}
+
+func (s *Server) run() {
+	exitCode := s.serve()
+	os.Exit(exitCode)
+}
+
+func (s *Server) serve() int {
+	var ctx context.Context //nolint:wsl // ctx must be declared before multi-assign
+
+	ctx, s.cancelFunc = context.WithCancel(
+		context.Background(),
+	)
+
+	go func() {
+		c := make(chan os.Signal, 1)
+
+		signal.Ignore(syscall.SIGPIPE)
+		signal.Notify(c, os.Interrupt, syscall.SIGTERM)
+
+		sig := <-c
+		s.log.Info("signal received", "signal", sig)
+
+		if s.cancelFunc != nil {
+			s.cancelFunc()
+		}
+	}()
+
+	go func() {
+		s.serveUntilShutdown()
+	}()
+
+	<-ctx.Done()
+	s.cleanShutdown()
+
+	return s.exitCode
+}
+
+const shutdownTimeout = 5 * time.Second
+
+func (s *Server) cleanShutdown() {
+	s.exitCode = 0
+
+	ctxShutdown, shutdownCancel := context.WithTimeout(
+		context.Background(),
+		shutdownTimeout,
+	)
+	defer shutdownCancel()
+
+	err := s.httpServer.Shutdown(ctxShutdown)
+	if err != nil {
+		s.log.Error(
+			"server clean shutdown failed",
+			"error", err,
+		)
+	}
+
+	s.log.Info("server stopped")
+}

script/bootstrap

@@ -0,0 +1,143 @@
+#!/bin/sh
+# script/bootstrap: install all dependencies needed to build and develop
+# this repo. Idempotent: every install is guarded by a check so already
+# installed tools are skipped. Base tooling comes from nix, apt, brew,
+# or apk (detected in that order); assumes nothing is present. Node is
+# used directly if installed; otherwise it is installed at a pinned
+# version via nvm (installing nvm itself first, from a hash-verified
+# release archive, never curl | sh).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# Pinned versions, 2026-07-07
+NODE_VERSION="22.17.0"
+NVM_VERSION="0.40.3"
+# sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz
+NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
+YARN_VERSION="1.22.22"
+
+PKGMGR=""
+SUDO=""
+APT_UPDATED=""
+
+detect_pkgmgr() {
+    [ -n "$PKGMGR" ] && return 0
+    if command -v nix-env >/dev/null 2>&1; then
+        PKGMGR="nix"
+    elif command -v apt-get >/dev/null 2>&1; then
+        PKGMGR="apt"
+    elif command -v brew >/dev/null 2>&1; then
+        PKGMGR="brew"
+    elif command -v apk >/dev/null 2>&1; then
+        PKGMGR="apk"
+    else
+        echo "bootstrap: no supported package manager (nix, apt, brew, apk)" >&2
+        exit 1
+    fi
+    if [ "$PKGMGR" = "apt" ]; then
+        export DEBIAN_FRONTEND=noninteractive
+        if [ "$(id -u)" != "0" ]; then
+            SUDO="sudo"
+        fi
+    fi
+}
+
+# pkg_install <nix-attr> <apt-pkg> <brew-formula> <apk-pkg>
+pkg_install() {
+    detect_pkgmgr
+    case "$PKGMGR" in
+        nix) nix-env -iA "nixpkgs.$1" ;;
+        apt)
+            if [ -z "$APT_UPDATED" ]; then
+                $SUDO env DEBIAN_FRONTEND=noninteractive apt-get update
+                APT_UPDATED=1
+            fi
+            $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2"
+            ;;
+        brew) brew install "$3" ;;
+        apk) apk add --no-cache "$4" ;;
+    esac
+}
+
+missing() {
+    ! command -v "$1" >/dev/null 2>&1
+}
+
+# verify_sha256 <file> <expected-hash>
+verify_sha256() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        actual="$(sha256sum "$1" | cut -d' ' -f1)"
+    else
+        actual="$(shasum -a 256 "$1" | cut -d' ' -f1)"
+    fi
+    if [ "$actual" != "$2" ]; then
+        echo "bootstrap: sha256 mismatch for $1" >&2
+        echo "  expected: $2" >&2
+        echo "  actual:   $actual" >&2
+        exit 1
+    fi
+}
+
+# nvm is a bash script; run a command in a bash with nvm loaded
+nvm_sh() {
+    bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*"
+}
+
+ensure_nvm() {
+    [ -s "$HOME/.nvm/nvm.sh" ] && return 0
+    # nvm prerequisites; nvm itself requires bash
+    if missing bash; then pkg_install bash bash bash bash; fi
+    if missing curl; then pkg_install curl curl curl curl; fi
+    if missing git; then pkg_install git git git git; fi
+    tmp="$(mktemp -d)"
+    curl -fsSL -o "$tmp/nvm.tar.gz" \
+        "https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz"
+    verify_sha256 "$tmp/nvm.tar.gz" "$NVM_SHA256"
+    mkdir -p "$HOME/.nvm"
+    tar -xzf "$tmp/nvm.tar.gz" -C "$HOME/.nvm" --strip-components=1
+    rm -rf "$tmp"
+}
+
+ensure_node() {
+    if ! missing node; then return 0; fi
+    ensure_nvm
+    nvm_sh "nvm install $NODE_VERSION"
+}
+
+ensure_yarn() {
+    if ! missing yarn; then return 0; fi
+    if ! missing corepack; then
+        corepack enable
+        corepack prepare "yarn@$YARN_VERSION" --activate
+    elif [ -s "$HOME/.nvm/nvm.sh" ]; then
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && corepack enable && \
+            corepack prepare yarn@$YARN_VERSION --activate"
+    else
+        npm install -g "yarn@$YARN_VERSION"
+    fi
+}
+
+install_js_deps() {
+    if missing yarn && [ -s "$HOME/.nvm/nvm.sh" ]; then
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && cd \"$ROOT\" && \
+            yarn install --frozen-lockfile"
+    else
+        yarn install --frozen-lockfile
+    fi
+}
+
+main() {
+    cd "$ROOT"
+
+    if missing make; then pkg_install gnumake make make make; fi
+    if missing git; then pkg_install git git git git; fi
+
+    ensure_node
+    ensure_yarn
+    install_js_deps
+
+    echo "bootstrap complete"
+}
+
+main "$@"

script/check

@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/check: run all checks (test, lint, fmt-check). Our own
+# extension to scripts-to-rule-them-all. Must not modify any files.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/test"
+    "$SCRIPT_DIR/lint"
+    "$SCRIPT_DIR/fmt-check"
+}
+
+main "$@"

script/cibuild

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/cibuild: run the CI build. The Dockerfile runs make check, so
+# a successful build implies all checks pass.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    docker build .
+}
+
+main "$@"

script/docker

@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/docker: build the Docker image tagged with the project name.
+# The tag comes from script/projectname.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    timeout 300 docker build -t "$("$SCRIPT_DIR/projectname")" .
+}
+
+main "$@"

script/fmt

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/fmt: format all files (writes).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    yarn prettier --write .
+}
+
+main "$@"

script/fmt-check

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/fmt-check: check formatting (read-only). Same scope as
+# script/fmt, but fails instead of writing.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    yarn prettier --check .
+}
+
+main "$@"

script/install-precommit

@@ -0,0 +1,16 @@
+#!/bin/sh
+# script/install-precommit: install the git pre-commit hook that runs
+# script/precommit. Our own extension to scripts-to-rule-them-all.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    hook=".git/hooks/pre-commit"
+    printf '#!/bin/sh\nset -e\nscript/precommit\n' > "$hook"
+    chmod +x "$hook"
+    echo "pre-commit hook installed: runs script/precommit"
+}
+
+main "$@"

script/lint

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/lint: run the linter (prettier in check mode).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    yarn prettier --check .
+}
+
+main "$@"

script/precommit

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/precommit: run by the git pre-commit hook; fails the commit if
+# checks fail. Our own extension to scripts-to-rule-them-all.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/check"
+}
+
+main "$@"

script/projectname

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/projectname: output the name of this project. Our own
+# extension to scripts-to-rule-them-all. Other scripts that need the
+# name (e.g. script/docker) call this, so they can stay identical
+# across all repos.
+set -eu
+
+main() {
+    echo "netwatch"
+}
+
+main "$@"

script/setup

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/setup: set up the repo for development after a fresh clone:
+# installs dependencies and the git pre-commit hook.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/bootstrap"
+    "$SCRIPT_DIR/install-precommit"
+}
+
+main "$@"

script/test

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/test: run the test suite. This repo has no unit tests; the
+# production build serves as the test (fails on broken code).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    timeout 30 yarn build
+}
+
+main "$@"

src/styles.css

@@ -21,3 +21,96 @@ body {
         rgba(255, 255, 255, 0) 100%
     );
 }
+
+/* ---- Mobile responsive layout (portrait / narrow viewports) ---- */
+@media (max-width: 768px) {
+    /* Header: stack title and controls vertically */
+    header .flex.items-center.justify-between {
+        flex-direction: column;
+        align-items: flex-start !important;
+        gap: 1rem;
+    }
+
+    header .flex.flex-col.items-end {
+        align-items: flex-start !important;
+        flex-direction: row;
+        flex-wrap: wrap;
+        gap: 0.75rem;
+    }
+
+    /* Pause button: smaller on mobile */
+    #pause-btn {
+        padding: 0.5rem 1rem;
+    }
+
+    #pause-btn svg {
+        width: 1.25rem;
+        height: 1.25rem;
+    }
+
+    #pause-text {
+        font-size: 0.875rem;
+    }
+
+    /* Summary box: wrap into a grid for readability */
+    #summary {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.25rem 0.5rem;
+        justify-content: center;
+        line-height: 1.6;
+    }
+
+    /* Hide the pipe separators on mobile */
+    #summary .text-gray-600.mx-3 {
+        display: none;
+    }
+
+    /* Host row: stack vertically */
+    .host-row .flex.items-center.gap-4 {
+        flex-direction: column;
+        align-items: stretch !important;
+        gap: 0.5rem;
+    }
+
+    /* Info section: full width, remove fixed width */
+    .host-row .w-\[420px\] {
+        width: 100% !important;
+        display: grid;
+        grid-template-columns: 1fr auto;
+        align-items: center;
+    }
+
+    /* Host name row with dot */
+    .host-row .flex.items-center.gap-2.min-w-\[200px\] {
+        min-width: 0;
+    }
+
+    /* Latency value: slightly smaller on mobile */
+    .host-row .latency-value {
+        font-size: 1.875rem;
+        line-height: 2.25rem;
+    }
+
+    /* Sparkline: full width below the info */
+    .host-row .sparkline-container {
+        width: 100%;
+        flex-shrink: 0;
+    }
+
+    /* Pin button: inline with the host info */
+    .host-row .pin-btn {
+        position: absolute;
+        right: 0.5rem;
+        top: 0.5rem;
+    }
+
+    .host-row {
+        position: relative;
+    }
+
+    /* Footer legend: wrap nicely */
+    footer p {
+        line-height: 1.8;
+    }
+}