server/CLAUDE.md

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
  • canvas_primitiv.md — Felles fritt-canvas underlag (pan, zoom, drag — brukes av whiteboard og storyboard)
  • universell_overfoering.md — Flytt objekter mellom blokker (drag-and-drop + "Send til...")
  • 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/retninger/ — Store arkitektoniske teser og retningsspørsmål (se README.md for oversikt):
  • status_quo.md — Hva Sidelinja er i dag: ambisiøse primitiver, tradisjonell overflate
  • rom_ikke_forum.md — Bør Sidelinja være et sanntidsrom fremfor en tradisjonell webapp?
  • universell_input.md — Én multimodal input/mottak-primitiv, noder + edges i stedet for separate tabeller
  • maskinrommet.md — Rust-tjenestelaget: fang, prosesser, lever — fast grensesnitt for alle tekniske tjenester
  • bruker_ikke_workspace.md — Brukeren er sentrum, workspaces er frivillige samlings-noder
  • datalaget.md — PG + Apache AGE som enhetlig graf og arkiv, migreringsstrategi
• 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/, docs/infra/ eller docs/retninger/ 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.