Web UI

The same Rust binary that serves /api/v1/* also serves a server-rendered HTML UI on the same port. Open http://<host>:<api-port>/ in a browser.

Stack

After cargo build --release you have one ~23 MB executable that contains every template, every CSS byte, and every vendored JS file. No node, no bundler, no separate frontend service.

Routes

Every mutation goes through /api/v1/*. There are no /web/* write routes — the JSON API stays the single source of truth, which means a future SvelteKit port is a templates-only rewrite. The /m/{token} share surface is read-only and serves no write method.

Build pipeline

cargo build [--release]
   └─► build.rs
         ├─► (first build only) scripts/fetch-tailwind.sh — downloads the Tailwind
         │     standalone CLI (~30 MB, not committed) for the host platform into bin/
         └─► ./bin/tailwindcss --minify
                --input  static/css/input.css
                --output static/css/app.css
   └─► rustc
         └─► rust-embed bakes static/ + templates/ into the binary

build.rs declares rerun-if-changed on templates/, src/, static/css/input.css, and scripts/fetch-tailwind.sh. Editing any of them triggers a Tailwind rebuild on the next cargo build.

Tailwind 4 scans both templates/**/*.html and src/**/*.rs for utility class names (declared via @source in input.css), so utility classes written inside Rust strings are preserved through tree-shaking.

Styling: the semantic layer

static/css/input.css is layered: design tokens (@theme, e.g. --color-ink) → primitives (.sticker-card, .sticker-btn, .sticker-pill) → semantic classes (.page-title, .panel-label, .kpi-value, .stat-tile, .status-badge--*, .btn-ghost, .sticker-btn--primary/--danger, .nav-link, .day-cell). Templates reference only the semantic names — no raw colour/shape utility clusters. State is one --modifier (.status-badge--down, .stat-tile--ok). Result: re-skinning the internal app is an input.css-only edit, no template touched. When adding UI, reuse/extend a semantic class rather than inlining bg-*/rounded-*/heading-scale clusters. The public status page is deliberately exempt — it’s a flat, brand-themed surface with its own view-supplied palette (public_status.rs), not the cartoon sticker system.

Dashboard refresh model

The dashboard splits into three regions:

1. Chrome (nav, page header) — rendered once.
2. Auto-refresh region (<div id="dashboard-region">) — KPI cards + system-health card. Polls /web/partials/dashboard every 5 s and swaps its own outer HTML so the trigger remains armed.
3. Charts (donut + 24h composition bar) — placed outside the refresh region so the ECharts instances persist across polls. The chart wrapper listens for htmx:afterSettle on the region and re-fetches /api/v1/dashboard/summary once per cycle, fanning out to both charts (single network round-trip, not one per chart).

The dashboard_summary handler caches its result in state.dashboard_cache for 5 s, so the polling load on Postgres + ClickHouse is bounded to one query set per 5 s regardless of how many tabs are open.

Credential redaction

For basic_auth and bearer_token the form runs a three-state machine in static/js/ui/auth_field.js:

The API rejects the *** sentinel on write as defence-in-depth — but the state machine prevents the form from ever submitting it. End-to-end coverage in tests/web_e2e_test.rs::edit_form_shows_redacted_auth_state_for_existing_target asserts that real credentials never appear in the rendered edit form.

Tests

cargo test --lib web::          # unit render tests
cargo test --test web_e2e_test  # end-to-end

Adding a new page

1. Add a template under templates/ extending base.html.
2. Add a #[derive(Template, WebTemplate)] struct and an axum handler in src/web/views/.
3. Register the route in src/web/routes.rs.
4. Tailwind picks up new utility classes automatically (the @source directive scans templates/**/*.html + src/**/*.rs).
5. Add a render test next to the view and, if there’s a route worth covering end-to-end, append a case to tests/web_e2e_test.rs.

Troubleshooting

Migrating to a SPA later

The design keeps a SPA port cheap. Every templates/*.html maps one-to-one to a Svelte (or React) component, every chart module under static/js/charts/ is already a pure (element, endpoint) → disposer function that imports unchanged into onMount, and there are zero /web/* write endpoints to refactor — only read partials. To swap frameworks:

1. Generate a typed JSON client from /api/openapi.json.
2. Port the templates page-by-page; keep /api/v1/* unchanged.
3. Drop src/web/views/ (keep src/web/assets.rs pointing at the new bundle).
4. Delete templates/ and static/js/{htmx,json-enc,ui} — no longer needed.

The backend (src/api/, src/storage/, src/scheduler/, src/worker/) stays untouched.