sidelinja/server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
server/CLAUDE.md
vegard 1e065b827d Dokumenter SpacetimeDB-loven: aldri PG-lekkasje i frontend/workers 
CLAUDE.md: Ny seksjon med fire eksplisitte regler for data som frontend viser.
synkronisering.md: §9 Workers som endrer synlig data — riktig vs feil flyt.
adapter_moenster.md: §5 Anti-pattern enrichFromPg — gjentatt 3+ ganger.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-16 17:19:57 +01:00

7.3 KiB
Raw Blame History

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.