tiny-forge/docs/reviews/functionality-review-2026-05-07.md

# Functionality Review — 2026-05-07

Last 5 commits reviewed:

1. `05440a5` feat(stats): resource metrics dashboard + sites logs/stats
2. `0632f51` feat(webhook): per-project and per-site webhook URLs
3. `e08acf5` refactor(settings): split General into focused pages
4. `03d58a0` fix: treat naive backend timestamps as UTC for relative labels
5. `90e6e59` feat: daemon health panel, brand-rail status chips, user timezone selector

Method: desk review of `git diff HEAD~5 HEAD` plus targeted reads of large
new components. No dev-server execution. Citations use absolute paths.

## TL;DR

- **Stats dashboard, daemon panel, timezone selector, settings split, and
  per-entity webhooks all wire end-to-end** — every Go endpoint added in
  these commits has a Svelte caller, every new field on the settings/health
  shapes is rendered, and i18n is parallel-keyed in `en.json` and `ru.json`.
- **One real flow gap:** the `WebhookPanel` confirm button (Project/Site
  detail) does not auto-close when regenerate succeeds in the "no current
  URL" case — it stays open until the user manually cancels. Minor.
- **i18n is 99 % complete but three hardcoded English fallbacks slipped in:**
  `'Docker daemon is not reachable.'` in `SystemDaemonsCard.svelte:98`, and
  `'Service status'` / `'Close sidebar'` aria-labels plus `'Docker daemon · …
  reachable'` / `'Proxy unreachable'` tooltips in `+layout.svelte` (lines
  194, 201, 208, 225). All three are user-visible.
- **Stats collector skips ticks when Docker is unreachable** but still calls
  `prune` — confirmed safe, but the very first sample after a Docker outage
  will show no system row for the outage window. Acceptable; documented in
  code.
- **Naive-UTC fix has full reach:** the fix lives in `toDate()` inside
  `web/src/lib/format/datetime.ts:34-46`, so every one of the 15 components
  that goes through `$fmt.*` benefits. `InstanceCard` was the only file
  that had its own ad-hoc parser; that parser is removed.

## Feature: Resource Metrics Dashboard (05440a5)

**What it claims:** background CPU/memory/network/block I/O collector with
configurable interval (5–300s, default 15) and retention (0–24h, default
2h). New host snapshot/history/top-N API endpoints, ECharts visualisation,
sites logs/stats reuse instance components, Docker-down 503 handling.

**What works**

- Collector lives in `internal/stats/collector.go:50-309`. It re-reads
  settings every tick (`run`/`readConfig`), so `/settings/maintenance`
  changes propagate within one tick. `interval=0` legitimately disables
  collection (`run` polls settings every minute in that branch).
- API endpoints and routing are wired: `internal/api/router.go:222,289-291,341-343`
  mounts `/api/system/stats`, `/api/system/stats/history`,
  `/api/system/stats/top`, plus the per-instance and per-site
  `/stats/history` endpoints, all behind the auth middleware.
- Frontend has matching helpers in `web/src/lib/api.ts:683-731`
  (`fetchSystemStats`, `fetchSystemStatsHistory`, `fetchTopContainers`,
  `fetchInstanceStatsHistory`, `fetchStaticSiteStats(s)History`,
  `fetchStaticSiteLogs`).
- `SystemResourcesCard.svelte:33-52` uses `Promise.allSettled` so a 503 on
  the live snapshot does not blank out history (which is read from SQLite
  and remains valid). Docker-unavailable detection at line 67 produces an
  amber banner with the i18n key `resources.dockerUnavailable`.
- `ContainerStats.svelte:13-15` and `ContainerLogs.svelte:14-16` define the
  `StatsSource`/`LogSource` discriminated unions exactly as the commit
  message describes; the site detail page uses both at
  `web/src/routes/sites/[id]/+page.svelte:255-279`.
- 30 m / 2 h / 6 h / 24 h window picker exists at
  `SystemResourcesCard.svelte:213-220`. `parseWindow` in
  `internal/api/stats_history.go:21-37` clamps any value to ≤ 24 h, so a
  hand-crafted `?window=999h` query returns the maxed window (good).
- History persistence survives backend restart — samples live in SQLite
  (`container_stats_samples`, `system_stats_samples`); migrations in
  `internal/store/store.go:128-180` create them additively with
  `IF NOT EXISTS`.

**Gaps / broken flows**

- **Top-consumer rows are unlabelled by name.** `SystemResourcesCard.svelte:259-264`
  shows only `s.container_id.slice(0,12)` plus an `instance | site` chip.
  No project/site name, so identifying the offender requires manual lookup.
  Backend already knows `owner_id`; resolving to a friendly name would be a
  one-extra-fetch fix.
- **No "stats off" UI hint.** When `stats_interval_seconds=0`, the
  collector idles and history endpoints return `[]`. Frontend just shows
  the "no samples yet" empty state with the *default* interval (15s)
  hardcoded in the message (`resources.noSamples` in `en.json:51`,
  `ru.json:51`) — it does not detect that collection is disabled. Users
  who toggle stats off will see a confusing "samples every 15s" message
  forever.
- **Stats settings live on Maintenance page, not on a dedicated card.**
  `web/src/routes/settings/maintenance/+page.svelte:117-132` has 4 fields
  (stale, prune, stats interval, stats retention) sharing one Save button.
  Not broken, but "Stats collection" is *not* maintenance — it's a runtime
  observability feature. Worth a follow-up split.
- **Top endpoint silently filters to last 2 minutes** (`stats_history.go:178`).
  If the collector interval is 300 s, two of the last three minutes have no
  samples and the top widget will look empty. Window should grow with
  interval, e.g. `max(2*interval, 2m)`.

**API/UI consistency**

- All snake_case ↔ snake_case (Go `json:"…"` tags match the TS types in
  `web/src/lib/types.ts:464-516`). Spot-checked
  `ContainerStatsSample`, `SystemStats`, `SystemStatsSample` — perfect
  alignment.
- One subtle naming asymmetry: in `SystemStats` (live snapshot) the field
  is `disk_total_bytes` and category breakdowns are `disk_images_bytes` etc.;
  in `SystemStatsSample` (history row) the field is just `disk_total_bytes`
  with no breakdown. The chart only uses workload CPU/memory percent, so
  this is fine, but a future "disk over time" chart would have to either
  query the live snapshot or the schema would have to grow.

**i18n**

- Full coverage. New keys live under `dashboard`, `resources`, and
  `statsSettings` namespaces, mirrored in `ru.json:42-87`. No untranslated
  strings in the touched files.

## Feature: Per-Project and Per-Site Webhook URLs (0632f51)

**What it claims:** replace global `settings.webhook_secret` with per-row
secrets on `projects` and `static_sites`; remove webhook-driven autocreate;
make site `sync_trigger=push|tag` actually trigger a sync.

**What works**

- Migration is additive and safe:
  `internal/store/store.go:131-138` adds `webhook_secret TEXT NOT NULL DEFAULT ''`
  to both tables and creates **partial unique indexes** (`WHERE webhook_secret != ''`)
  at `store.go:240-241`, so multiple legacy rows with empty secrets do not
  collide.
- Lazy backfill via `EnsureProjectWebhookSecret` /
  `EnsureStaticSiteWebhookSecret` (`internal/store/projects.go:158-171`,
  `internal/store/static_sites.go:296-308`). UI calls `GET /webhook` first,
  which triggers backfill — old projects "just work" the first time you
  open them.
- Routing in `internal/webhook/handler.go:127-133`:
  `POST /api/webhook/{secret}` for projects, `POST /api/webhook/sites/{secret}`
  for sites. Both return 404 for unknown/empty secrets (no information leak).
  The order (`/sites/{secret}` first, then `/{secret}`) is correct chi-wise
  because the literal `sites` segment beats the catch-all.
- `siteRefMatches` (`internal/webhook/matcher.go:46-90`) implements push and
  tag separately, with empty-Branch ⇒ accept-any-heads, and empty-TagPattern
  ⇒ `*`. Manual sites short-circuit at `handler.go:295-303`.
- Tests cover both happy and sad paths:
  - `internal/webhook/matcher_test.go` (push, tag, manual, empty branch,
    `ParseImageRef` cases)
  - `internal/webhook/handler_test.go` (unknown-secret 404, image mismatch,
    no-stage-match 200/skip, site push match, site manual skip,
    site branch mismatch).
- `WebhookPanel.svelte` is generic, used by both detail pages
  (`projects/[id]/+page.svelte:771-776`, `sites/[id]/+page.svelte:283-288`).
  Absolutises the URL with `window.location.origin` at line 30 so users can
  copy a working URL.
- Old global routes removed: no `/api/settings/webhook-url` or
  `/api/settings/webhook-url/regenerate` in the diff (router.go:387-388
  shows the deletion).

**Gaps / broken flows**

- **WebhookPanel race / minor UX**: `handleRegenerate` (lines 47-57) hides
  the confirm strip *before* the network call. If the call fails, the user
  sees the toast but the regenerate button reappears with no inline state.
  Acceptable, but a "retry" affordance would help.
- **Project image guardrail bypass when `project.Image` is empty.**
  `handler.go:206-214`: the check is `if project.Image != "" && !imageMatches(...)`.
  A project with an unset image accepts *any* image. Fine if treated as
  intentional (commit message says guardrail is misconfig protection, not
  security), but worth flagging.
- **No "test webhook" button anywhere.** With per-entity URLs, users have
  no way to verify before pointing CI at it. The git diff doesn't add a
  ping endpoint either. Follow-up.
- **Settings › Integrations page has a dead-end card** for incoming
  webhooks (`integrations/+page.svelte:91-94`): just text saying "go to
  the project page". No link, no list of projects. Adds friction.

**API/UI consistency**

- `WebhookUrlResponse` shape matches between Go (`internal/api/webhooks.go:17-20`)
  and TS (`web/src/lib/api.ts:325-328`).
- `Project.WebhookSecret` and `StaticSite.WebhookSecret` use `json:"-"`
  (`internal/store/models.go:14, 253`) — secrets never leak through the
  general project/site list endpoints. Good.

**i18n**

- New keys `projectDetail.webhookTitle/webhookDesc`, `sites.webhookTitle/webhookDesc`,
  `webhookPanel.*`, `settingsIntegrations.*` exist in both `en.json` and
  `ru.json`. Verified parallel structure.

## Feature: Settings Page Split (e08acf5)

**What it claims:** split the 547-line `settings/+page.svelte` into
focused pages; group the sidebar; each page does its own partial PUT.

**Sidebar groups** (from `+layout.svelte:32-50` and `64-72`):

- *Overview*: General, Integrations
- *Routing*: Registries, NPM/Traefik (conditional), DNS
- *System*: Maintenance, Backups
- *Security*: Authentication

**Old setting → new page mapping**

| Old setting (HEAD~5 `+page.svelte`) | New location | Status |
|---|---|---|
| Domain / Server IP / Public IP | `/settings` (Overview) | ✓ kept |
| Network / Subdomain pattern | `/settings` | ✓ kept |
| Polling interval / Base volume path | `/settings` | ✓ kept |
| Notification URL | `/settings/integrations` | ✓ moved |
| Stale threshold | `/settings/maintenance` | ✓ moved |
| Image prune threshold | `/settings/maintenance` (Danger zone card) | ✓ moved |
| Prune Images button | `/settings/maintenance` | ✓ moved into separate Danger card |
| Wildcard DNS / Cloudflare token / Zone | `/settings/dns` | ✓ moved |
| Test DNS connection | `/settings/dns` | ✓ moved |
| Proxy provider radio | `/settings` | ✓ kept (with link to /settings/{npm|traefik}) |
| **Global webhook URL** | n/a — feature removed (per-entity now) | ✓ intentional |
| Stats interval / retention (NEW) | `/settings/maintenance` | ✓ added in same commit's diff |

**Verdict:** every setting from the old page is reachable. Nothing
orphaned. Credentials page (`/settings/credentials/+page.svelte`) was
deleted and the sidebar entry was already gone at HEAD~5, so no broken
link. Tested: the sidebar's `provider`-conditional NPM / Traefik items
still work (`+layout.svelte:54-55`).

**Gaps / broken flows**

- **Each page issues an independent `getSettings()` on mount.** Navigating
  through the sidebar reloads the entire 30-field settings blob each time.
  Not broken, but a shared cache or layout-level fetch would halve the
  payload. Follow-up.
- **Save scoping is correct** — each page builds a `Partial<Settings>` of
  only its own keys (e.g. `maintenance/+page.svelte:54-59`). Confirmed by
  reading all four split pages.
- **DNS page does not have an inline link to fall back from "test failed"**
  to the General/proxy page. Minor.

**i18n**

- New `settings.groupMain/groupProxy/groupSystem/groupSecurity`,
  `settingsDns.*`, `settingsIntegrations.*`, `settingsMaintenance.*`,
  `statsSettings.*`, `settingsGeneral.globalConfigDesc/configureNpm/...`
  all present in both locales.

## Fix: Naive UTC Timestamp Handling (03d58a0)

**Reach:** the fix is in `toDate()` (`web/src/lib/format/datetime.ts:34-46`)
via `normalizeIsoUtc`. **Every** consumer of `$fmt.*` therefore inherits
the fix:

```
web/src/routes/+layout.svelte
web/src/routes/+page.svelte
web/src/routes/projects/+page.svelte
web/src/routes/projects/[id]/+page.svelte
web/src/routes/projects/[id]/volumes/[volId]/browse/+page.svelte
web/src/routes/sites/+page.svelte
web/src/routes/sites/[id]/+page.svelte
web/src/routes/stacks/+page.svelte
web/src/routes/stacks/[id]/+page.svelte
web/src/routes/settings/backup/+page.svelte
web/src/lib/components/EventLogEntry.svelte
web/src/lib/components/InstanceCard.svelte
web/src/lib/components/StaleContainerCard.svelte
web/src/lib/components/TimezoneSelector.svelte
```

**Audit for stragglers:** `Grep new Date(` across the frontend returns 5
files. Two are inside `format/datetime.ts` and `stores/timezone.ts` (the
fix itself); two are in the `TimezoneSelector` and `+layout.svelte` clock
ticker (`new Date()` with no input — current time, not affected); one is
`routes/events/+page.svelte:55` building a `since` *query parameter* that
is sent to the backend, never displayed. Conclusion: **fix has 100 % reach
for displayed timestamps**.

`InstanceCard.svelte` lost its private `timeSinceCreated` parser
(commit diff lines 32-43); now uses `$fmt.relative(instance.created_at)`.

## Feature: Daemon Health Panel + Timezone Selector (90e6e59)

### Daemon health panel

**What it claims:** rich Docker /info + /version + NPM aggregates exposed
via `/api/health`; status chips moved into the brand block; new
`SystemDaemonsCard` on the dashboard; shared health store de-duplicates
the 30 s poll.

**What works**

- `GET /api/health` (`internal/api/health.go:6-39`) now returns
  `database`, `docker` (+ rich info), and conditionally `proxy` (with
  NPM aggregates). 8 s timeout, NPM fields fetched only when ping succeeds
  so an offline proxy doesn't amplify latency.
- `health.ts:38-66` shared store with single 30 s poll; the layout
  consumes it via `$health.docker/proxy/checked` (`+layout.svelte:53-56`)
  and `SystemDaemonsCard.svelte:13-19` does the same. No duplicate
  fetches — verified by the `inFlight` guard at `health.ts:37`.
- Both panels render the rich payload: container running/paused/stopped
  stacked bar, version/api/platform/kernel/cpu/memory/storage/images,
  latency, root dir. Proxy panel shows total vs managed proxy hosts (with
  proportion meter), access lists, certificates.
- Brand-rail chips at `+layout.svelte:201-242` show DKR + NPM/TRF, with
  pulse animation classes (`chip-live`/`chip-down`), running container
  count, and proxy host count. Click on a down chip toggles `hintsExpanded`.

**Daemons checked, by name:**

- **Docker Engine** — connected via socket; "unhealthy" means the ping
  failed (text from `Ping`) or the client wasn't initialised. The user
  hint is `daemons.dockerHint` ("Check that the Docker daemon is running…").
- **Proxy provider** — only checked when one is configured (NPM or Traefik).
  "Unhealthy" means `Ping` failed; the panel surfaces `proxy.error` and
  the configured URL. If proxy_provider=`none`, panel shows
  "Not configured" with a CTA link to `/settings`.
- **Database** — included in the JSON response but not surfaced on the
  daemons card. The brand-rail also does not show a DB chip; if SQLite
  is unreachable the chip rail goes "BOOT" forever (since
  `health.ts:50-57` falls back to `prev.docker ?? {connected:false}` and
  drops `database`). Minor — but a permanently-unreachable SQLite would
  leave the user wondering why everything is dead with no indicator.

**Gaps / broken flows**

- **Hardcoded English fallbacks** (i18n leak):
  - `web/src/routes/+layout.svelte:194` `aria-label="Close sidebar"` (was already English)
  - `web/src/routes/+layout.svelte:201` `aria-label="Service status"` (new in this commit)
  - `web/src/routes/+layout.svelte:208` tooltip
    `` `Docker daemon · ${dockerHealth?.version ?? 'reachable'}` `` —
    "Docker daemon" and "reachable" are English literals; commit added this code
  - `web/src/routes/+layout.svelte:208` fallback `'Docker unreachable'`
  - `web/src/routes/+layout.svelte:225` fallback `'Proxy unreachable'`
  - `web/src/lib/components/SystemDaemonsCard.svelte:98` fallback
    `'Docker daemon is not reachable.'`
- **Refresh button has no debounce window**, only an in-flight guard
  (`SystemDaemonsCard.svelte:53-61`). Spamming it triggers serial calls.
  Acceptable.
- **No DB-down indicator** anywhere visible to the user. Edge case but
  worth noting.

**API/UI consistency**

- All Docker fields the frontend consumes (`web/src/lib/types.ts:258-285`)
  are emitted by `dockerHealth` in `internal/api/health.go:60-100`. Cross-checked
  every key (version, api_version, os, arch, kernel, storage_driver, root_dir,
  ncpu, memory_total, containers, running, paused, stopped, images,
  latency_ms). Matches.
- `ProxyHealth` TS shape (`types.ts:289-296`) matches Go fields:
  `provider`, `connected`, `error`, `latency_ms`, `url`, `proxy_hosts`,
  `proxy_hosts_managed`, `access_lists`, `certificates`. Matches.

**i18n**

- `daemons.*` namespace fully translated in both `en.json:917-953` and
  `ru.json:917-953` (parallel keys verified). The hardcoded strings above
  are the only gaps.

### Timezone selector

**What it claims:** user IANA timezone preference with auto-detect,
applied across all `$fmt.*` rendering, persisted in localStorage.

**Persistence**

- Stored at `localStorage.dw_timezone` via subscriber on the `timezonePreference`
  writable (`web/src/lib/stores/timezone.ts:12,55-59`). Re-read on next page
  load by `getInitialPreference` (lines 44-50). Validates the IANA string
  before accepting it, falling back to `auto`.
- "Auto" is a sentinel; `effectiveTimezone` derives a concrete IANA zone
  from `Intl.DateTimeFormat().resolvedOptions().timeZone` on every read
  (lines 66-69), so changing browser zone with auto enabled re-resolves.

**Application reach**

- `effectiveTimezone` is consumed by `makeFormatters` in `datetime.ts:117-119`,
  which is the single source for the entire `$fmt` reactive store. Every
  `$fmt.dateTime`, `$fmt.date`, `$fmt.relative` etc. respects the user
  zone. **Verified across all 15 consumers listed under the naive-UTC fix
  section.**
- One subtle case: `$fmt.relative` is timezone-independent (`datetime.ts:142-156`),
  which is correct — "5 m ago" doesn't depend on display zone.

**Gaps / broken flows**

- **Selector lives only on `/settings`.** Reasonable home, but no quick
  "switch zone" affordance from the brand rail or top bar; you have to
  navigate. Minor.
- **No backend record.** The preference is browser-local, so logging in
  on a fresh device shows server time. Commit message acknowledges this
  ("purely client-side preference"). Acceptable.

**i18n**

- Full `timezone.*` namespace in both locales (`en.json:1117-1136`,
  `ru.json:1117-1136`). Picker placeholder is translated.

## Cross-cutting Issues

### i18n leaks

Three runtime strings in user-visible places are still English-only:

1. `web/src/routes/+layout.svelte:201` `aria-label="Service status"` (new)
2. `web/src/routes/+layout.svelte:208,225` chip tooltips include
   English literals (`'Docker daemon'`, `'reachable'`, `'Docker unreachable'`,
   `'Proxy unreachable'`).
3. `web/src/lib/components/SystemDaemonsCard.svelte:98` fallback message
   when `docker.error` is empty.

`+layout.svelte:194` (`Close sidebar`) was already English at HEAD~5; not a
regression but worth fixing while in the area.

### Naming consistency

- Backend uses `snake_case` JSON tags everywhere (`disk_total_bytes`,
  `latency_ms`, `proxy_hosts_managed`). TypeScript interfaces use the same.
  No drift detected.
- One naming asymmetry: `Settings.WebhookSecret` was deleted from the
  Go struct — clean removal. `internal/store/static_sites.go:233`,
  `projects.go:53` use new column. SQLite column `webhook_secret` on
  `settings` table is left alone (per the migration comment); no row
  emits it, so it's dead weight but harmless.

### Dashboard polling

`SystemResourcesCard` polls every 15 s on its own (`SystemResourcesCard.svelte:79`).
`ContainerStats` polls every 30 s. `health` store polls every 30 s.
`navCounts` store polls separately. Multiple uncoordinated timers; OK in
practice, but a future optimisation candidate.

### Confirm dialog UX

Both `WebhookPanel` and the maintenance "Prune Images" Danger zone use
inline confirms / `ConfirmDialog`. Consistent. The brand-rail "click a down
chip to expand hints" is a third confirm-ish pattern, fine but not
discoverable.

## Suggested Follow-ups (prioritized)

1. **Localise the three hardcoded English strings** in
   `web/src/routes/+layout.svelte:194,201,208,225` and
   `SystemDaemonsCard.svelte:98`. ~15 min, replaces 5 literals with
   `$t('daemons.…')` keys (which already exist for most cases — e.g.
   `daemons.docker`, `daemons.offline`).
2. **Add owner-name resolution to the "top consumers" widget**
   (`SystemResourcesCard.svelte:259-264`). Currently only a 12-char ID +
   `instance|site` chip; users have no way to know which container is
   spiking.
3. **Detect "stats collection disabled" (`stats_interval_seconds=0`) and
   tailor the empty-state message** in `SystemResourcesCard.svelte`
   instead of always saying "samples every 15 s".
4. **Remove the dead `webhook_secret` column on `settings`** in a future
   destructive migration window, OR officially document it as deprecated
   in the schema comment.
5. **Add a "Test webhook" button to `WebhookPanel.svelte`** — POSTs a
   minimal payload to the URL and surfaces the response. Replaces
   guesswork when wiring CI.
6. **Add a DB-down indicator** to the brand rail (a 3rd chip "DB"). The
   data is already in `/api/health`; only the UI needs the chip.
7. **Top-N samples 2-minute window** in `internal/api/stats_history.go:178`
   should scale with collector interval (`max(2*interval, 2m)`) so users
   on slow intervals don't see a falsely-empty widget.
8. **Settings › Integrations dead-end card** — link to the Projects and
   Sites lists rather than just text saying "go look there".
9. **Auto-close the WebhookPanel confirm strip on success** (it already
   resets, but the strip stays visible until the user clicks Cancel).