# 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.