synops/docs/concepts/adminpanelet.md

# Adminpanelet — Serveradministrasjon

## Oversikt

Sentralt administrasjonspanel for hele Synops-instansen. Tilgjengelig
kun for server-admins (Vegard). Dekker alt som ikke er per-samling:
AI-konfigurasjon, ressursstyring, systemvarsler og serverhelse.

Adminpanelet er en del av SvelteKit-frontenden, bak egen
tilgangskontroll (admin-edge til server-noden eller Authentik-gruppe).

## Moduler

### 1. AI Gateway-styring

Konfigurasjon av LiteLLM og modellruting. Ref: `docs/infra/ai_gateway.md`.

- **Modelloversikt:** Liste over tilgjengelige modeller med status, kostnad per token, latens-snitt
- **API-nøkler:** Legg til, rotér og deaktiver nøkler for OpenRouter, Anthropic, Google, xAI osv. Nøkler vises aldri i klartekst etter lagring
- **Ruting-regler:** Hvilken modell brukes for hvilken jobbtype (transkripsjonsanalyse, oppsummering, tagging, diktat-cleanup osv.)
- **Fallback-kjeder:** Primærmodell → fallback → siste utvei. Per jobbtype
- **Forbruksoversikt:** Aggregert ressursforbruk per samling, per jobbtype, per tidsperiode. Dekker AI-tokens, Whisper-tid, TTS-tegn, CAS-lagring, båndbredde og LiveKit-tid. Ref: `docs/features/ressursforbruk.md`
- **Prompt Lab-tilgang:** Snarvei til testing av prompts mot faktisk data. Ref: `docs/features/prompt_lab.md`

### 2. Ressursstyring

Kontroll over CPU, minne og prioritering av bakgrunnsjobber.

- **Jobbkø-oversikt:** Aktive, ventende og feilede jobber. Filtrer på type, samling, status. Manuell retry/avbryt
- **Prioritetsregler:** Konfigurer relativ prioritet mellom jobbtyper (f.eks. live transkripsjon > batch-transkripsjon > embedding-generering)
- **Ressursgrenser:** Maks samtidige jobber per type, CPU/minne-grenser per worker-container
- **Ressurs-governor:** Automatisk nedprioritering av tunge jobber (Whisper, embedding) under aktive LiveKit-sesjoner. Konfigurerbar terskel
- **Disk-status:** CAS-lagring, PG-størrelse, mediefiler. Visuell oversikt med varsling ved terskelverdier (ref: pruning-logikk i `docs/retninger/maskinrommet.md`)

### 3. Systemvarsler og vedlikeholdsmodus

Varsle brukere om planlagt nedetid, oppdateringer eller hendelser.
Kritisk for å unngå avbrudd midt i møter, podcast-opptak eller
publisering.

#### Varslingsmekanisme

- **Sanntidsvarsel via WebSocket:** Maskinrommet skriver en varslingsnode
  som frontend abonnerer på via WebSocket. Vises som banner/toast i alle
  aktive klienter umiddelbart
- **Varslingstyper:**
  - `info` — generell melding (f.eks. "Ny funksjonalitet tilgjengelig")
  - `warning` — planlagt vedlikehold med nedtelling
  - `critical` — umiddelbar handling kreves
- **Nedtelling:** Admin setter tidspunkt for vedlikehold. Frontend
  viser nedtelling: "Serveren restartes om 15 minutter"
- **Aktive sesjoner-sjekk:** Før vedlikehold, vis oversikt over pågående
  aktivitet:
  - Aktive LiveKit-rom (møter, opptak)
  - Brukere med ulagrede endringer (collaboration-sesjoner)
  - Pågående jobbkø-jobber
- **Graceful shutdown-sekvens:**
  1. Varsel sendes X minutter i forveien (konfigurerbart, default 15 min)
  2. Nye LiveKit-rom blokkeres etter varsling
  3. Påminnelse ved T-5 min og T-1 min
  4. Jobbkøen stopper å plukke nye jobber
  5. Vent til aktive jobber fullføres (med timeout)
  6. Restart

#### Implementert (oppgave 15.2)

- **Backend:** `maskinrommet/src/maintenance.rs` — `MaintenanceState` med atomiske flagg
  og bakgrunns-shutdown-koordinator
- **API-endepunkter:**
  - `POST /intentions/initiate_maintenance` — starter nedtelling med tidspunkt
  - `POST /intentions/cancel_maintenance` — avbryter planlagt vedlikehold
  - `GET /admin/maintenance_status` — viser status + kjørende jobber
- **Frontend:** `/admin` — vedlikeholdspanel med statusvisning, aktive sesjoner
  og initier/avbryt-knapper
- **Jobbkø:** `jobs.rs` sjekker `maintenance.is_active()` før dequeue
- **LiveKit:** `join_communication` blokkerer nye tokens under vedlikehold
- **Shutdown-flyt:** Vent til `scheduled_at` → sett `active` → vent på jobber
  (5 min timeout) → `process::exit(0)` → systemd restarter

#### Varslingsnode

```jsonc
{
  "node_kind": "system_announcement",
  "title": "Planlagt vedlikehold",
  "content": "Serveren oppdateres kl. 22:00. Forventet nedetid: 10 minutter.",
  "metadata": {
    "announcement_type": "warning",
    "scheduled_at": "2026-03-17T22:00:00Z",
    "expires_at": "2026-03-17T22:30:00Z",
    "blocks_new_sessions": true
  }
}
```

Vises for alle med `visibility: open`. Forsvinner automatisk etter
`expires_at`.

### 4. Serverhelse

Sanntidsoversikt over systemtilstand.

- **Tjeneste-status:** PG, Caddy, Authentik, LiteLLM, Whisper, LiveKit — oppe/nede/degradert
- **Metrikker:** CPU, minne, disk, nettverkstrafikk
- **PG-helse:** Tilkoblingspool, aktive spørringer, replikerings-lag (fremtidig)
- **Logg-tilgang:** Siste feil og advarsler fra alle tjenester, filtrerbart
- **Backup-status:** Siste vellykkede backup per type, neste planlagte kjøring

#### Implementert (oppgave 15.6)

- **Backend:** `maskinrommet/src/health.rs` — parallelle helsesjekker for alle
  tjenester, system-metrikker via `/proc`, PG-statistikk, backup-sjekk, logg-tilgang
- **API-endepunkter:**
  - `GET /admin/health` — komplett helse-dashboard (tjeneste-status, CPU/minne/disk,
    PG-stats, backup-status)
  - `GET /admin/health/logs?service=&lines=` — logg-tilgang per tjeneste eller alle
- **Frontend:** `/admin/health` — dashboard med tjenestekort (opp/nede/degradert med
  latens), system-metrikker med progress-bars, PG-tilkoblinger og DB-størrelse,
  backup-status, og filtrerbar logg-visning
- **Tjeneste-sjekker:** PG (SQL ping), Caddy (admin-API),
  Authentik (health-endpoint), LiteLLM/Whisper/LiveKit (HTTP health). Alle kjøres
  parallelt med 5s timeout
- **Metrikker:** CPU load via `/proc/loadavg`, minne via `/proc/meminfo`,
  disk via `statvfs`, oppetid via `/proc/uptime`
- **Logger:** Systemd-journal for native tjenester (maskinrommet, caddy),
  `docker logs` for containere. Filtrerbart per tjeneste, konfigurerbart antall linjer
- **Backup:** Sjekker standard backup-kataloger for PG-dump og CAS-filer.
  Rapporterer status som ok/stale/missing basert på filens alder

### 5. Bruker- og tilgangsoversikt

- **Aktive brukere:** Hvem er pålogget nå, siste aktivitet
- **Authentik-integrasjon:** Snarvei til Authentik admin for brukerhåndtering
- **Samlingsoversikt:** Alle samlinger med eier, traits, størrelse, aktivitetsnivå

## Tilgang

Adminpanelet er *ikke* en trait — det er en plattformfunksjon som
eksisterer utenfor samlings-modellen. Tilgang styres via:

- Authentik-gruppe `synops-admin`
- Eller `admin`-edge til en dedikert server-node

Vanlige brukere ser aldri adminpanelet. Ruten er skjult og
tilgangskontrollert server-side.

#### Implementert (oppgave 15.3)

- **Backend:** `maskinrommet/src/jobs.rs` — `list_jobs()`, `count_by_status()`,
  `distinct_job_types()`, `retry_job()`, `cancel_job()`
- **API-endepunkter:**
  - `GET /admin/jobs?status=&type=&collection_id=&limit=&offset=` — jobbliste med filtre
  - `POST /intentions/retry_job` — sett feilet jobb tilbake til pending
  - `POST /intentions/cancel_job` — avbryt ventende jobb
- **Frontend:** `/admin/jobs` — jobbkø-oversikt med statusoppsummering,
  filtrer på status/type, paginering, retry/avbryt-knapper
- **Migrasjon:** `013_job_queue.sql` — formaliserer job_queue-tabellen med
  indekser for admin-spørringer

## Implementeringsstrategi

Adminpanelet bygges inkrementelt. Første prioritet er det som trengs
for daglig drift:

1. **Systemvarsler** — kritisk for å unngå avbrudd (implementert: 15.1)
2. **Jobbkø-oversikt** — nødvendig for feilsøking (implementert: 15.3)
3. **AI Gateway-konfigurasjon** — nødvendig når AI-features aktiveres
4. **Serverhelse** — nyttig men ikke blokkerende
5. **Ressursstyring** — optimalisering, kan vente