# Sidelinja - Claude Code Prosjektguide

## Prosjektoversikt
Sidelinja er et redaksjonelt operativsystem og kunnskapsgraf for podcast-produksjon.
Self-hosted på Hetzner VPS med full datakontroll.

## Arbeidsflyt
- **Standard arbeidsmodus:** Start i planleggingsmodus. Lag en grundig plan, få godkjenning, deretter implementer. Jobbene er ment å kunne kjøre lenge autonomt uten input underveis.
- **Testmiljø:** `./dev.sh` er den kanoniske måten å starte utviklingsmiljøet. Når nye tjenester, steg eller oppsett-quirks oppdages, oppdater alltid `dev.sh` slik at kunnskapen bevares i scriptet — ikke bare i hodet. Før Vegard tester i browser: kjør `./dev.sh`, verifiser med `cargo check`/`svelte-check`/`curl`, og meld tilbake at det er klart.
- **Browser-testing:** Claude har ikke tilgang til browser. Visuell testing og interaksjon gjøres av Vegard. Claude kan verifisere backend (kompilering, API-kall, database-state) men ikke frontend-rendering.
- **Commit og push:** Bruk egen vurdering. Commit når arbeidet er logisk komplett, push til Forgejo når det gir mening. Ingen grunn til å spørre — det er trygt og reverserbart.
- **Deploy til produksjon:** Krever alltid eksplisitt godkjenning fra Vegard. Deploy = SSH til server + pull + docker compose up. Aldri gjør dette uten å spørre først.
- **Diskusjon:** Forklar og diskuter før arkitekturendringer eller uvanlige valg. For implementering innenfor eksisterende spec — bare kjør.

## Dokumentasjonstre
CLAUDE.md er eneste startdokument. Alt annet ligger under `docs/`:

- `docs/arkitektur.md` — Overordnet arkitektur, stack, datamodell, infrastruktur, bygge-rekkefølge
- `docs/setup/` — Oppsett og drift:
  - `produksjon.md` — Steg-for-steg oppsett av Hetzner VPS fra scratch
  - `lokal.md` — Steg-for-steg oppsett av lokalt WSL2 utviklingsmiljø
  - `migration_safety.md` — Sjekkliste for PostgreSQL-migrasjoner (RLS-verifisering)
- `docs/concepts/` — Brukeropplevelser (integrerte produkter):
  - `studioet.md` — Podcast-innspilling (LiveKit + Live AI + Aha-markør)
  - `møterommet.md` — Interne møter (LiveKit + AI-referent + Whiteboard)
  - `redaksjonen.md` — Daglig redaksjonelt arbeid (Chat + Kanban + Research)
  - `podcastfabrikken.md` — Publiseringspipeline (Whisper + AI + RSS)
  - `kunnskapsgrafen.md` — Utforsking og redigering av kunnskapsnettverk
  - `valgomaten.md` — Publikumsrettet crowdsourced valgomat
  - `den_asynkrone_gjesten.md` — Asynkrone gjestebidrag via tidsbegrenset lenke
- `docs/features/` — Tekniske byggeklosser (brukes av flere konsepter):
  - `kunnskapsgraf_og_relasjoner.md` — Nodes & Edges datamodell i PostgreSQL
  - `meldingsboks.md` — Universell diskusjonsprimitiv (erstatter chat/kanban-kort/kalender/faktoider/notater)
  - `chat.md` — Trådet chat med mentions og autocomplete
  - `kanban.md` — Drag-and-drop planlegging
  - `kalender.md` — Redaksjonell kalender med abonnementsmodell og ICS-eksport
  - `notater.md` — Scratchpad/notatblokk med auto-save og debounce
  - `whiteboard.md` — Sanntids frihåndstavle (møterom, chat, solo)
  - `live_transkripsjon.md` — Whisper-pipeline (felles motor for studio/møter/fabrikk)
  - `live_ai.md` — Live AI: faktoid-oppslag (studio) + referent (møter)
  - `visuell_graf.md` — Interaktiv graf-visning
  - `lydmeldinger.md` — Lydmeldinger, diktering og tale-til-tekst
  - `podcast_statistikk.md` — IAB-kompatibel lytterstatistikk fra Caddy-logger
  - `kunnskaps_bridge.md` — Cross-workspace discovery via vector embeddings
  - `prompt_lab.md` — Internt verktøy for testing og deploy av LLM-prompts
  - `brukerinnstillinger.md` — Personlige innstillinger (tema, skrift, editor-preferanser)
- `docs/infra/` — Infrastruktur (ikke brukersynlig):
  - `jobbkø.md` — Felles PostgreSQL-basert køsystem for alle bakgrunnsjobber
  - `synkronisering.md` — PostgreSQL ↔ SpacetimeDB dataflyt og eierskapsmodell
  - `api_grensesnitt.md` — Kommunikasjonskart: SvelteKit er web-API, Rust er worker
  - `ai_gateway.md` — LiteLLM som sentralisert AI-ruter (BYOK + OpenRouter fallback)
- `docs/proposals/` — Halvtenkte idéer og kreative innfall (se `README.md` for oversikt)
- `docs/erfaringer/` — Lærdommer fra implementering (feller, anti-patterns, løsninger):
  - `svelte5_reaktivitet.md` — $state-getters, SSR-feller, polling-mønster
  - `spacetimedb_integrasjon.md` — SDK-konvensjoner, BigInt, Rust borrow-feller
  - `adapter_moenster.md` — Hybrid PG+SpacetimeDB, anti-patterns, anbefaling for neste komponent
  - `authentik_oidc.md` — Sub-claim er SHA256, @auth/sveltekit JWT-quirks, redirect URI

## Stack
- **Backend/Automasjon:** Rust
- **Frontend:** SvelteKit (TypeScript, PWA)
- **Sanntid:** SpacetimeDB (arbeidsflyt/state) + LiveKit (lyd/video)
- **Database:** PostgreSQL (persistent/kunnskapsgraf) + SpacetimeDB (in-memory/sanntid)
- **AI:** faster-whisper (transkripsjon), LiteLLM (AI Gateway → Gemini/Claude/Grok/OpenRouter)
- **Infra:** Docker Compose, Caddy, Authentik (SSO), Forgejo (Git)

## Produksjonsserver
- **IP:** 157.180.81.26
- **SSH:** `ssh sidelinja@157.180.81.26` (nøkkelbasert, sudo uten passord)
- **Filer:** `/srv/sidelinja/` (docker-compose.yml, .env, config/, data/, media/, logs/)
- **Git repos:**
  - `server` — app-kode, infra, arkitektur: `ssh://git@git.sidelinja.org:222/sidelinja/server.git`
  - `sidelinja` — podcastinnhold (transkripsjoner, show notes, research): `ssh://git@git.sidelinja.org:222/sidelinja/sidelinja.git`
- **Domener:** sidelinja.org, auth.sidelinja.org (Authentik), git.sidelinja.org (Forgejo), vegard.info

## Viktige regler
- Aldri eksponere databaseporter mot internett (kun port 80/443 via Caddy)
- Bruk `tea` CLI, ikke `gh` (vi bruker Forgejo, ikke GitHub)
- Tunge AI-jobber (Whisper, LLM-kall) skal aldri blokkere web-requests
- All AI-kode peker på `http://ai-gateway:4000/v1` — aldri direkte til leverandør-APIer
- Kod og test lokalt i WSL2, deploy via push til Forgejo + SSH pull
- Sjekk alltid relevant doc i `docs/concepts/`, `docs/features/` eller `docs/infra/` før du implementerer
- Sjekk `docs/erfaringer/` for kjente feller før du implementerer med Svelte 5, SpacetimeDB eller adapter-mønsteret
- Etter ferdig implementering av en komponent: dokumenter lærdommer i `docs/erfaringer/`

## SpacetimeDB-loven (les `docs/infra/synkronisering.md` for detaljer)
SpacetimeDB er autoritativ sanntidskilde for data som frontend leser. **All kode** — frontend-adaptere, workers, bakgrunnsjobber — følger disse reglene:

1. **Frontend → SpacetimeDB.** Aldri direkte PG-kall for data som SpacetimeDB eier (chat, kanban, markører). Ingen `enrichFromPg`, ingen PG-polling, ingen metadata-hacks.
2. **Worker → SpacetimeDB → PG.** En worker som endrer data frontend ser (f.eks. AI-vask av meldinger) skriver resultatet til SpacetimeDB via reducer. Sync-workeren persisterer til PG i bakgrunnen. Worker leser fra PG (jobbkø, prompts), men skriver synlig resultat til SpacetimeDB.
3. **Nytt felt = utvid SpacetimeDB-modulen.** Trenger frontend `metadata`, `edited_at` eller `revisjoner`? Legg det til i SpacetimeDB-modulen, ikke hack rundt med PG API-kall fra frontend.
4. **PG er backup, ikke snarvei.** PG-adaptere er fallback for miljøer uten SpacetimeDB. De er ikke en "enklere vei" for nye features.