notify-bridge/.claude/docs/frontend-architecture.md

Frontend Architecture Notes

Stack

• SvelteKit 2 + Svelte 5 + Tailwind CSS v4 — Static adapter with SPA fallback. Dev proxy to :8420.
• Tailwind CSS v4: Uses @theme directive in app.css for CSS variables.

Svelte 5 Runes

• $state only works in .svelte and .svelte.ts files. Regular .ts files cannot use runes — use plain variables instead.

i18n

• Uses $state rune in .svelte.ts file. Locale auto-detects from localStorage.
• t() is reactive via $state. setLocale() updates immediately without page reload.

Auth Flow

• After login/setup, use window.location.href = '/' (hard redirect), NOT goto('/').

Overlays

IMPORTANT: Overlays (modals, dropdowns, pickers) MUST use position: fixed with inline styles and z-index: 9999. Tailwind CSS v4 fixed/absolute classes do NOT work reliably inside flex/overflow containers in this project. Always calculate position from getBoundingClientRect() for dropdowns, or use top:0;left:0;right:0;bottom:0 for full-screen backdrops.

Entity Cache System

Shared entities use a $state-based cache layer in frontend/src/lib/stores/:

• entity-cache.svelte.ts — Generic cache factory with 30s TTL, request deduplication, and local mutation helpers (upsert, remove, set).
• caches.svelte.ts — Singleton caches for: providersCache, targetsCache, trackingConfigsCache, templateConfigsCache, telegramBotsCache, emailBotsCache, matrixBotsCache, commandConfigsCache, commandTemplateConfigsCache.

How pages use caches

• Cross-page references (e.g. providers on the Trackers page): Use $derived(providersCache.items) and call providersCache.fetch() in load(). Cached data is returned instantly if fresh (<30s).
• Owning pages (e.g. Providers page itself): Use $derived(providersCache.items) and call providersCache.fetch(true) (force refresh) in load().
• After mutations (create/update/delete): The owning page calls cache.invalidate() then load() to force-refresh. Other pages pick up changes on next navigation via TTL expiry.
• On logout: clearAllCaches() is called to wipe all cached data.

Adding a new cached entity

1. Add a type to frontend/src/lib/types.ts
2. Add export const fooCache = createEntityCache<Foo>('/foo'); to caches.svelte.ts
3. Add fooCache.clear() to clearAllCaches()
4. In page components: replace let foo = $state<Foo[]>([]) with let foo = $derived(fooCache.items) and replace api('/foo') with fooCache.fetch()

Provider-Aware UI

IMPORTANT: UI labels for collections, template variables, and icons MUST be dynamic per provider type — never hardcode Immich-specific terms like "Albums" or mdiImageMultiple where other providers will appear.

• TrackerForm (TrackerForm.svelte): Uses collectionMeta lookup by providerType for collection label, icon, placeholder, and description.
• Template variables (/api/template-configs/variables): Must return variable definitions for ALL provider types (Immich, Gitea, Planka, NUT, Scheduler), not just Immich. When adding a new provider, add its slot variables to _<provider>_variables() in template_configs.py.
• Grid items (grid-items.ts): New provider types must be added to BOTH providerTypeItems AND providerTypeFilterItems.

UI Conventions

Selector Placeholders

IMPORTANT: Selector/dropdown placeholder text must be plain and simple — no decorative dashes or special characters. Use Select provider... or Tracking Configs, NOT — Select provider — or -- Tracking Configs --. The i18n keys already follow this convention; never wrap them with '— ' + t('key') + ' —' in Svelte templates.