puppy-tracker/README.md

# puppy-tracker

A tiny offline-first PWA for tracking your puppy's sleep, meals, pees, poos,
weight, and training.
The browser is the primary client; a small Go server provides a shared
source-of-truth and sync between devices.

## How sync works

- Each event has a UUID and an `updatedAt` timestamp.
- Mutations (add / edit / delete) happen against `localStorage` first, so the
  app keeps working when offline. Deletes are recorded as tombstones so they
  can propagate.
- On app load, on `online`, on every mutation (debounced), and every 60 s, the
  client POSTs its full event list to `/api/events/sync`. The server merges
  it with its own copy using last-write-wins on `updatedAt` and returns the
  merged set.
- The server keeps its copy in a SQLite database (`puppy.db`); events and the
  shared profile are separate tables, and last-write-wins is enforced by the
  upsert itself. On first start it auto-imports any legacy `events.json` /
  `config.json` sitting alongside it, renaming them to `*.imported`.
- Service worker bypasses cache for `/api/*` so writes always hit the server
  when online; static assets are still cached for offline use.
- Training exercises (name + how-to instructions) are their own synced
  collection with the same contract as events (UUIDs, last-write-wins,
  tombstones) via `POST /api/exercises/sync`. Training sessions are ordinary
  events (`type: "training"`) referencing an exercise by id, so they ride the
  event sync unchanged.
- The puppy's name and birthday are a per-account profile stored on the host
  (`GET`/`PUT /api/config`), so a new device picks them up automatically instead
  of being configured per-client. The client caches the last-seen values in
  `localStorage` for offline/instant paint and reconciles with the server by
  last-write-wins on `updatedAt`. The age shown in the header (in weeks and
  months) is derived from the birthday.
- All data is scoped to the signed-in account (see [Accounts](#accounts)): every
  event, profile and photo carries a `user_id`, and `localStorage` is namespaced
  per user so two accounts on one browser never mix.

A status pill in the header shows `syncing…` / `synced 2m ago` / `pending` /
`sync error` / `offline`. Tap it to force-sync.

## Layout

```
puppy-tracker/
├── flake.nix         # packages (server, static, default), devShell, nixosModule
├── module.nix        # systemd unit, StateDirectory, hardening
├── server/
│   ├── go.mod
│   ├── go.sum
│   ├── main.go       # SQLite store, LWW sync, static file serving
│   └── auth.go       # accounts, sessions, invite-gated registration
└── src/              # the web app
    ├── index.html
    ├── app.js
    ├── style.css
    ├── sw.js
    ├── manifest.json
    └── icon.svg
```

## Run locally

```sh
nix run                       # http://localhost:8080, data in $XDG_DATA_HOME/puppy-tracker
PUPPY_ADDR=:9000 nix run      # custom port

# Registration needs an invite code (see Accounts). Set it in the environment:
PUPPY_INVITE_CODE=letmein nix run

# Hot-iterate (data in /tmp):
nix develop -c sh -c 'cd server && go run . -static ../src -data /tmp/puppy.db -invite-code letmein'
```

## Accounts

The app is multi-tenant: each person signs in and sees only their own puppy's
events, profile and photos.

- **Sessions.** Passwords are hashed with bcrypt; login mints a random session
  token stored (hashed) in the `sessions` table and set as an `HttpOnly` cookie.
  `/api/*` (except `login`/`register`/`logout`) requires a valid session.
- **Registration is invite-gated.** Sign-up requires the shared secret passed via
  `-invite-code` / `PUPPY_INVITE_CODE`. With no code set, registration is
  disabled (existing accounts can still log in). Share the code with whoever you
  want to give an account.
- **First account adopts existing data.** When accounts are introduced on a DB
  that already had single-tenant data (or that imported a legacy `events.json`),
  the first account to register inherits all of it — events, profile and photos.
- **Self-service deletion.** Settings → *Delete account* removes the signed-in
  account and everything it owns (`DELETE /api/me`, re-confirming the password):
  events, profile, sessions and the photo directory are all wiped.
- **Serve over HTTPS in production.** Session cookies are only marked `Secure`
  when you pass `-secure-cookies` (enable it behind a TLS proxy), so passwords
  aren't sent in the clear.

## Pedigree lookup

Set your dog's SKK chip or registration number in **Settings** (it rides the
synced profile, next to name and birthday). Once set, a 🌳 button appears that
opens a page rendering that dog's ancestry as a tree.

- SKK has no public API, so the server drives the interactive site the way a
  browser would: it resolves the id to SKK's internal dog id, fetches the
  pedigree page (7 generations per request), and follows each generation's leaves
  deeper. A lookup returns the first generations immediately and keeps crawling in
  the background; the client polls and fills the tree in as ancestors arrive.
- Because a deep crawl is dozens of sequential upstream requests, finished trees
  are cached per dog in the `pedigree_cache` table (pedigrees don't change), and
  the id→dog resolution is memoised, so a dog is only ever crawled once and repeat
  opens hit SKK zero times. The client also mirrors the finished tree in
  `localStorage`, so the page paints instantly and shows the last-known tree even
  offline.
- The lookup is behind auth like the rest of `/api/*`; the first trace of a new
  dog needs to reach SKK, but after that it works from cache (including offline).

## Use it on NixOS

In your system flake:

```nix
{
  inputs.puppy-tracker.url = "path:/path/to/puppy-tracker";

  outputs = { self, nixpkgs, puppy-tracker, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        puppy-tracker.nixosModules.default
        {
          services.puppy-tracker = {
            enable = true;
            port = 8080;
            openFirewall = true;
            # Registration secret, kept out of the Nix store. The file holds:
            #   PUPPY_INVITE_CODE=some-shared-secret
            inviteCodeFile = "/run/secrets/puppy-invite-code";
            # Enable once you terminate TLS in front of the service.
            secureCookies = false;
          };
        }
      ];
    };
  };
}
```

The server runs as a `DynamicUser` systemd unit. Data is stored in a SQLite
database at `/var/lib/puppy-tracker/puppy.db` via `StateDirectory` (with photos
alongside it under `photos/`).

## Notes

- Accounts gate access, but there is no built-in TLS. If exposing publicly,
  terminate TLS with a reverse proxy in front (Caddy / nginx / Tailscale Funnel)
  and set `secureCookies = true`. Without HTTPS, passwords and session cookies
  travel in the clear.