# Local/remote-aware service tiles — design

**Date:** 2026-06-08
**Status:** Approved (design), pending plan
**Component:** Void 2.0 Sacred Valley → Little Blue health band service tiles

## Problem

Every service in the health registry has a single `url`, almost always a LAN
address (`http://192.168.1.x:port`, see `config/services.json`). The tile links
straight to it (`public/components/service_tile.js` → `href: safeHref(s.url)`).
When the owner opens the dashboard from off-network (e.g. via `void.hynesy.com`),
those private IPs are unreachable, so tiles like **Gramps** (`http://192.168.1.99`)
open dead links. A few services already paper over this by storing a domain as their
`url` (Jellyfin, Chaptarr), which is inconsistent and breaks local-speed access.

## Goal

Tiles open the **right URL for where the owner is**: LAN address when on-network,
domain when remote — with a reliable, always-available manual fallback to the other
URL, and a clear "LAN-only" indication for services not exposed externally.

## Non-goals

- Changing how the **health checker** works. It runs server-side on CT 311 (on the
  LAN) and must keep probing the LAN `url`. This change only affects the **tile link**
  in the browser.
- Automatic probe-then-fallback. Rejected — see Decisions.
- Auto-discovering domains. The owner curates `external` per service.

## Decisions (from brainstorming)

| Fork | Decision |
|---|---|
| Primary URL selection | **Context-based**: derived from `location.hostname` (public host ⇒ remote ⇒ domain; private IP/localhost/.local ⇒ local ⇒ LAN url) |
| Domain data source | **Explicit optional `external` field** per service in `services.json`; pre-filled from CF/Traefik `*.hynesy.com` conventions, owner corrects |
| "Fallback regardless" | **Manual one-click alt control** on each tile that opens the *other* URL. NOT an auto-probe |
| Remote + no `external` | Tile shown but **dimmed + "LAN-only" badge** |
| Styling | Blackflame-styled, sized/aligned to existing tile elements, reuse themed classes |

### Why not automatic probe-then-fallback

When remote, the dashboard is served over HTTPS. Silently probing an
`http://192.168.x.x` address from an HTTPS page is blocked by the browser's
mixed-content policy, and cross-origin (`no-cors`) probes return opaque results that
can't distinguish "reachable" from "errored". So an auto-probe would be unreliable
precisely when remote — the case it exists for. **Navigating** (clicking a link) to
either URL is always allowed, so a manual alt-link is the robust realization of
"fallback regardless".

## Architecture

### Data
- `monitored_services` gains a nullable `external text` column.
- `config/services.json` services gain an optional `"external"` string.
- Two existing services that store a domain in `url` are normalised: `url` becomes the
  LAN address, `external` becomes the domain:
  - `jellyfin`: `url` → `http://192.168.1.230:8096`, `external` → `https://jellyfin.hynesy.com`
  - `chaptarr`: `url` → `http://192.168.1.230:8789`, `external` → `https://chaptarr.hynesy.com`

### Server
- `lib/db/repos/monitored_services.js`: add `external` to `COLS`, `toSvc`, `create`
  (default `null`), `PATCHABLE`, and the `upsertDiscovered` insert (always `null` —
  discovered LAN scans have no domain).
- `lib/api/routes/health.js`:
  - Add `external: s.external` to the per-service object in the `GET /services` payload.
  - Add `external: z.string().url().optional()` to `svcBody` (so owner add/edit can set it).
- Migration `lib/db/migrations/022_monitored_services_external.sql`: `ALTER TABLE
  monitored_services ADD COLUMN external text;` **plus** `UPDATE ... SET external=...
  WHERE id=...` backfill for the curated IDs — because the live instance is already
  seeded (`seedFromConfig` is a no-op once rows exist), so the column add alone wouldn't
  populate domains on deployed instances.

### Client (pure, unit-testable core)
New module `public/views/service_url.js`:
- `isRemoteHost(hostname)` → boolean. Remote = NOT (`localhost`, IPv4 private ranges
  `10.`, `172.16–31.`, `192.168.`, `127.`, `*.local`, `*.lan`, bare hostname with no dot).
- `pickServiceUrls(svc, remote)` → `{ primary, alt, lanOnly }`:
  - remote: `primary = svc.external || svc.url`; `alt = svc.external ? svc.url : null`;
    `lanOnly = !svc.external`.
  - local: `primary = svc.url`; `alt = svc.external || null`; `lanOnly = false`.
  - `alt` is null when it would equal `primary`.

### Tile (`public/components/service_tile.js`)
- Compute `{ primary, alt, lanOnly }` via `pickServiceUrls(s, isRemoteHost(location.hostname))`.
- Main anchor → `safeHref(primary)`.
- If `alt`: render a small secondary anchor (themed glyph, e.g. `⇄`) →
  `safeHref(alt)`, `target="_blank" rel="noreferrer"`, with a `title` naming the alt
  ("Open via LAN" / "Open via domain"). Click must not also trigger the main anchor.
- If `lanOnly`: add `lan-only` class (dim) + a small "LAN-only" badge.

### Pre-filled `external` values (owner to verify/correct)
Confident (CF/Traefik confirmed): `void-server`→void, `gramps`, `plex`, `tdarr`,
`sonarr`, `radarr`, `jellyfin`, `chaptarr`. Likely (wiki): `bookstack`. All others
remain LAN-only until the owner adds a domain.

## Error handling / edge cases
- Missing `external` → LAN-only path (no alt; dimmed when remote). No errors.
- `safeHref` already guards bad schemes; both primary and alt pass through it.
- Existing seeded DB rows: migration 022 adds `external` (NULL) AND backfills the curated
  domains by `id`, so the deployed (already-seeded) instance gets them without a re-seed.
  Fresh/empty instances also get them via `services.json` on first seed.

## Testing
- Unit (pure): `isRemoteHost` (private/public/localhost/.local/bare cases) and
  `pickServiceUrls` (remote+external, remote+none, local+external, local+none, alt-equals-
  primary dedupe).
- API: `GET /services` includes `external`; `POST /services` accepts/round-trips `external`.
- Tile/contract: tile renders alt control when alt present; `lan-only` class + badge when
  remote and no external; main href is primary. (jsdom; `location.hostname` stubbed.)
- Repo: `create`/`update` persist and return `external`.

## Files
- Create: `lib/db/migrations/022_monitored_services_external.sql`,
  `public/views/service_url.js`, `tests/frontend/service_url.test.js`
- Modify: `config/services.json`, `lib/db/repos/monitored_services.js`,
  `lib/api/routes/health.js`, `public/components/service_tile.js`, `public/style.css`,
  and the relevant existing tests (`tests/api/health.test.js`, tile/contract test).