# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## What This Is Self-hosted website analytics, single-operator. Tracks page views, clicks, scrolls, sessions, and custom events. Properties (tracked sites) embed a collector script that POSTs JSON to `/collect`. The dashboard renders metric cards, time-series charts, world map, and PDF/markdown reports for any date range. Single-binary axum app, no Django, no multi-user. Password from `.env`. Originally a Django service; data from that era was migrated in via `./analytics migrate ` and the Django code has been retired. ## Commands - **Dev server:** `make run` (runs Vite watch + cargo run concurrently on port 8000) - **Production build:** `make build` (Vite assets + topojson maps + release binary) - **Run release binary:** `make start` - **Pull production data:** `make pull` (rsync db + geoip from `git remote server`) - **Rebuild map data:** `make maps` (regenerates per-country topojson) - **Seed fake data:** `make seed` (creates/refreshes a "Seed Test" property with realistic events; override `SESSIONS=2000 DAYS=60`) - **Import a Django DB:** `make migrate FROM= [FORCE=1]`: one-shot import that preserves property UUIDs (so embedded snippets keep working). Same logic is exposed on the binary as `./analytics migrate [--force]` so the production Docker image can run it. - **Docker build:** `sudo docker build .` There are no tests or linters configured. ## Architecture **Backend:** Single-binary axum app (`src/main.rs`). Async sqlx + sqlite (WAL, `synchronous=NORMAL`, `busy_timeout=5s`, foreign keys on) for both reads and writes. Schema lives in `migrations/0001_initial.sql` and is applied automatically on boot. State is shared via `AppState` (template env, db pool, cookie key, geoip + ua parsers, dashboard cache, config). **Auth:** Single password from `ANALYTICS_PASSWORD` in `.env`. Login form posts to `/login`; on success a signed cookie (`SameSite=Strict`, 30-day max-age) is set. The cookie payload is just `1:`, signed with `tower-cookies`. The cookie key is `ANALYTICS_COOKIE_SECRET` if set, else derived from the password via SHA-512 (so changing the password invalidates sessions). No CSRF tokens; `SameSite=Strict` is the protection. **Data model:** Three tables. `properties` holds tracked sites (UUID PK, name, custom_cards JSON, is_protected, is_public). `events` stores human events with hot fields extracted into typed columns (url, referrer, user_agent, country, region, city, lat/lon, screen size, platform/browser/device, utm_*, time_on_page_ms, user_id) plus an `extra` JSON blob for custom keys. `bot_events` is a separate table with the small subset of fields useful for bot reporting; bot traffic is routed there at write time so human dashboard queries never have to filter it. `meta` is a key-value table for things like the Proprium property id. **Collector flow:** `POST /collect` (also `/collect/` for compat) accepts `{collectorId, event, data}` JSON. It looks up the property, normalizes the referrer to a bare hostname, runs GeoIP enrichment (via `maxminddb` against `data/db.mmdb`) on `session_start`, parses the user agent (via `uaparser` against `data/regexes.yaml`), and either inserts into `events` or `bot_events` based on the parsed bot flag. CORS is fully open on this endpoint. Client IP is read from `X-Forwarded-For` first, then `X-Real-IP`. **Self-tracking (Proprium):** On first boot the binary auto-creates a "Proprium" property with `is_protected=1` and stores its UUID in the `meta` table. The base template renders a collector snippet pointing at that property when `BASE_URL` is set, so the app tracks its own usage like any other site. **Auto-downloads:** On boot, two best-effort background tasks download `data/db.mmdb` (DB-IP City Lite, CC-BY-4.0, no signup) if missing or older than 30 days, and `data/regexes.yaml` (canonical ua-parser regexes from the `ua-parser/uap-core` repo, Apache-2.0) if missing. Failures are logged and the server still boots. UA parsing falls back to a substring heuristic and GeoIP enrichment is skipped. **Templates:** Jinja2 templates in `templates/` rendered by minijinja with a Jinja2-faithful HTML formatter so `/` is not escaped to `/` (matches status/blog/darkfurrow). The `vite_asset` global resolves hashed asset names by reading `dist/.vite/manifest.json`: re-read per call in debug builds (Vite watcher rebuilds show up immediately), cached at startup in release builds. **Frontend pipeline:** Vite (run from `frontend/`) builds `frontend/static_src/` into `dist/`. Four entry points: `base` (Bootstrap 5 SCSS + monaspace font + the bootstrap JS shell), `pages` (marketing pages), `properties` (dashboard charts + map), `collector` (the public embed script). Output filenames are content-hashed and served at `/static/`. **Map data:** `frontend/scripts/build_maps.js` (run at Docker build time via `bun run build:maps`) downloads Natural Earth admin-0 110m + admin-1 10m GeoJSON and writes per-country TopoJSON files into `static_maps/`. The Rust binary serves that directory at `/static_maps/`. The world view ships with the dashboard; per-country admin-1 is lazy-fetched on click. **PDF generation:** `src/pdf.rs` embeds the Typst compiler (`typst` + `typst-pdf`) as a library, no chromium subprocess. `PdfRenderer::new` runs typst-kit's font searcher once at startup and shares the resulting library/book/font slots across renders. The dashboard route renders a Typst template through minijinja first (using the `typst_md` and `typst_str` filters in `templates.rs` to escape user data into Typst-safe markup), then passes the resulting source to `PdfRenderer::render` inside `tokio::task::spawn_blocking` (Typst compilation is CPU-bound and synchronous). `?report=md` returns the markdown variant directly. **Request logging:** `src/main.rs::log_requests` middleware prints `time METHOD STATUS latency path` per request with ANSI-colored status codes (green 2xx, cyan 3xx, yellow 4xx, red 5xx). Sub-microsecond cost. ## Layout ``` analytics/ ├── Cargo.toml, Cargo.lock # rust deps ├── Makefile, README.md # top-level ├── migrations/ # sqlx migrations (0001_initial.sql) ├── src/ # rust source │ ├── main.rs # tiny entry: env init, subcommand dispatch, server boot │ ├── app.rs # AppState::from_env + router() (assembles per-feature routes) │ ├── render.rs # render() helper (injects standard ctx) │ ├── middleware.rs # request log + 404 handler │ ├── routes/ # per-feature route modules, each exposing fn router() │ │ ├── mod.rs │ │ ├── auth.rs # /login, /logout, is_authenticated │ │ ├── home.rs # /, /changelog, /documentation │ │ ├── seo.rs # /favicon.ico, /robots.txt, /sitemap.xml │ │ ├── properties.rs # /properties (list/create/delete/custom-cards/visibility) │ │ ├── dashboard.rs # / dashboard, ?report=pdf|md │ │ └── collector.rs # POST /collect with UA + GeoIP enrichment + bot routing │ ├── db.rs # sqlx pool init, migrate, ensure_proprium │ ├── models.rs # Property + PropertyRow structs │ ├── queries.rs # dashboard aggregations │ ├── geoip.rs # maxminddb wrapper + DB-IP auto-download + reload │ ├── ua.rs # uap-rs wrapper + regexes auto-download │ ├── pdf.rs # embedded Typst renderer │ ├── migrate.rs # `./analytics migrate ` │ ├── bin/seed.rs # `cargo run --bin seed` to seed a "Seed Test" property │ └── templates.rs # minijinja env, vite_asset, url_for, jinja2-compat formatter ├── templates/ # minijinja-compatible jinja2 │ ├── base.html # layout │ ├── includes/ # collector, messages, social │ ├── registration/ # login form │ ├── properties/ # properties list + dashboard │ └── pages/ # home, changelog, documentation ├── frontend/ # JS pipeline (package.json, vite.config.js, static_src/) │ ├── static_src/ │ │ ├── base/ # bootstrap scss + base scripts (entry: index.js) │ │ ├── pages/ # marketing styles │ │ ├── properties/ # dashboard chart + map JS │ │ └── collector/ # public embed │ └── scripts/build_maps.js # natural earth → topojson ├── dist/ # vite build output (gitignored, served at /static/) ├── static_maps/ # topojson per country (gitignored, served at /static_maps/) ├── data/ # sqlite db + geoip mmdb + regexes.yaml at runtime (gitignored) ├── target/ # cargo build output (gitignored) ├── Dockerfile, docker-compose.yml └── samplefiles/ # Caddyfile.sample, env.sample, post-receive.sample ``` The binary reads `templates/`, `dist/`, `migrations/`, and `static_maps/` from cwd by default. Override the project root with `ANALYTICS_ROOT=` and the data directory with `ANALYTICS_DATA_DIR=` (production sets the latter to `/data`). ## Key Routes - `/`: marketing home (redirects to `/properties` when authenticated) - `/login`, `/logout`: single-password auth - `/properties`: list + create + delete + custom cards + visibility toggle (auth required) - `/`: dashboard (auth required unless property is public). Accepts `?date_start`, `?date_end`, `?date_range`, `?filter_url`, `?report=pdf|md`. - `/collect`, `/collect/`: public collector endpoint (CORS-open, accepts JSON POST) - `/changelog`, `/documentation`, `/favicon.ico`, `/robots.txt`, `/sitemap.xml`: static pages - `/static/*`: Vite assets (1y cache header) - `/static_maps/*`: topojson per country (1y cache header) ## Tooling - **Rust deps:** managed with `cargo` (`Cargo.toml`, `Cargo.lock`) - **JS deps:** managed with `bun`, run from `frontend/` (`frontend/package.json`, `frontend/bun.lock`) - **Production:** Docker (`rust:alpine` builder + `alpine:3.23` runtime, no chromium since PDF is embedded Typst). Runtime image installs `font-jetbrains-mono`, `ttf-dejavu`, `ttf-liberation`, and `fontconfig` so Typst can find a body sans, mono, and fallback fonts. Deployed via `git push server master` triggering a post-receive hook that runs `docker compose up --build --detach`. Data persisted to `/srv/data/analytics/`. ## Status of the port The port is feature-complete against the original Django version: - Login, properties CRUD, dashboard with all 16 metric/chart/list aggregations, custom cards, public toggle, collector with UA + GeoIP enrichment + bot routing, PDF + markdown report export, world map with admin-1 drill-down, self-tracking via Proprium, auto-download of geoip + uaparser regexes, Dockerfile + samplefiles for the standard `git push server master` deploy. - The dashboard's frontend JS (Chart.js charts, d3-geo + topojson world map, custom-card form, public toggle, filter chips, date selector) is the original code; the server-side context shape matches what those scripts expect. Possible future work (none of it required for parity): - Custom-cards POST currently accepts a JSON array but the in-page form uses checkbox names. The form-handler JS posts JSON, so this works; if the JS ever stops sending JSON, the endpoint would need to accept form-encoded too. - Auto-download of the DB-IP mmdb fails on the first day or two of every month while DB-IP rolls the new file. The code retries on next boot. For production set up `restic-status`-style monthly cron via `make pull` if you need stronger guarantees.