# Synops — Claude Code Prosjektguide

## Prosjektoversikt
Synops er en plattform for redaksjonelt arbeid og podcast-produksjon.
Self-hosted på Hetzner VPS med full datakontroll.

Synops er plattformen. Sidelinja (podcastredaksjonen) er en tenant —
en organisasjon som bruker Synops. Denne distinksjonen er bevisst:
plattformkode og infrastruktur er skilt fra tenant-data og -innhold.

## 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.
- **Alt skjer på serveren.** Claude Code kjører direkte på produksjonsserveren
  (`/home/vegard/synops/`). Rust, Node.js og Docker er tilgjengelig.
  Bygging, testing og deploy skjer her. Vegard kobler til via SSH/tmux.
- **Browser-testing:** Claude har ikke tilgang til browser. Visuell testing
  gjøres av Vegard. Claude verifiserer backend (kompilering, API, DB-state).
- **Commit og push:** Bruk egen vurdering. Trygt og reverserbart.
- **Deploy til produksjon:** Krever alltid eksplisitt godkjenning fra Vegard.
- **Diskusjon:** Forklar og diskuter før arkitekturendringer.
  For implementering innenfor eksisterende spec — bare kjør.

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

- `docs/arkitektur.md` — Overordnet arkitektur, lagmodell, teknologivalg
- `docs/retninger/` — Arkitektoniske teser og vedtatte retninger:
  - `README.md` — Oversikt og status
  - `status_quo.md` — Hva v1 var: ambisiøse primitiver, tradisjonell overflate
  - `rom_ikke_forum.md` — Opplevelse-først, to-lags-modell, administrativ opplevelse
  - `universell_input.md` — Tre primitiver (input, mottak, kommunikasjon), noder+edges
  - `maskinrommet.md` — Rust-orkestrator: fang, prosesser, lever
  - `bruker_ikke_workspace.md` — Noder er sentrum: brukere, team, innhold er noder. Tilgangsmatrise fra edges.
  - `datalaget.md` — PG(+AGE) som graf og arkiv, SpacetimeDB som sanntidslag
- `docs/primitiver/` — Spesifikasjoner for kjerneprimitivene:
  - `nodes.md` — Node-skjema, node_kind, visibility, CAS-noder, eierskap
  - `edges.md` — Edge-skjema, typer, metadata, systemedges
  - `traits.md` — Trait-system: evner/funksjonalitet for samlingsnoder, katalog, pakker
  - (kommer: input, mottak, kommunikasjonsnode)
- `docs/concepts/` — Brukeropplevelser/produktområder:
  - `studioet.md`, `møterommet.md`, `redaksjonen.md`, `podcastfabrikken.md`,
    `kunnskapsgrafen.md`, `valgomaten.md`, `den_asynkrone_gjesten.md`,
    `publisering.md`, `adminpanelet.md`
- `docs/features/` — Tekniske byggeklosser:
  - Se individuelle filer for chat, kanban, kalender, meldingsboks,
    kunnskapsgraf, whiteboard, live transkripsjon, ressursforbruk, m.fl.
- `docs/proposals/` — Idébank med 32+ uimplementerte forslag (se README.md)
- `docs/setup/` — Oppsett og drift:
  - `produksjon.md` — Steg-for-steg oppsett av Hetzner VPS fra scratch
  - `lokal.md` — Historisk: lokalt utviklingsmiljø (WSL2). Utdatert — all utvikling skjer nå på serveren.
  - `migration_safety.md` — Sjekkliste for PostgreSQL-migrasjoner (v1 workspace-RLS, trenger omskriving til node_access)
- `docs/infra/` — Infrastruktur og drift:
  - `ai_gateway.md` — LiteLLM som sentralisert AI-ruter (BYOK + fallback)
  - `api_grensesnitt.md` — Kommunikasjonskart: SvelteKit er web-API, Rust er worker
  - `jobbkø.md` — PostgreSQL-basert køsystem for bakgrunnsjobber
  - `synkronisering.md` — PostgreSQL ↔ SpacetimeDB dataflyt og eierskapsmodell
  - `claude_agent.md` — Claude som chat-deltaker: arkitektur, triggere, sikkerhet
- `docs/erfaringer/` — Lærdommer fra v1 (adapter-mønster, Svelte 5, SpacetimeDB, Authentik)
- `reference/` — Kode fra v1 med gjenbruksverdi (Editor.svelte)
- `ops/` — Repeterbare vedlikeholdsjobber (ryddejobb, doc-audit, drift-sjekk)

## Aktører
- **Vegard** — serveradmin, utvikler, bruker. Kobler til via SSH/tmux.
- **Claude** — AI-agent, utvikler. Kjører direkte på serveren (`/home/vegard/synops/`).
- Begge har sudo + docker-tilgang på serveren.

## Stack
- **Orkestrator/Backend:** Rust (maskinrommet) — kjører native på hosten
- **Frontend:** SvelteKit (TypeScript, PWA)
- **Sanntid:** SpacetimeDB
- **Database/Graf:** PostgreSQL (+Apache AGE ved behov)
- **Binærlagring:** CAS (content-addressable store)
- **AI:** Claude Code (chat-agent), LiteLLM (AI Gateway), faster-whisper (STT)
- **Infra:** Docker Compose, Caddy, Authentik (SSO), systemd

## Driftsmodell
- **Maskinrommet** kjører direkte på hosten som systemd-tjeneste (`maskinrommet.service`),
  ikke i Docker. Dette gir tilgang til `claude` CLI for agent-chat.
  Bygges med `cargo build --release`, startes med `sudo systemctl restart maskinrommet`.
- **Øvrige tjenester** (PG, STDB, Caddy, Authentik, Whisper, LiteLLM) kjører i Docker.
- **Caddy** bruker `host.docker.internal` for å nå maskinrommet på hosten.
- **Claude som chat-deltaker:** Agent-node (`d3eebc99-...-a44`) i grafen. Legg Claude
  til som `member_of` i en kommunikasjonsnode → alle meldinger trigger `agent_respond`-jobb
  → maskinrommet kaller `claude -p` → svar skrives tilbake i chatten.
- **Kill switch:** `UPDATE agent_identities SET is_active = false WHERE agent_key = 'claude-main'`

## Produksjonsserver
- **IP:** 157.180.81.26
- **SSH:** `ssh vegard@157.180.81.26`
- **Root-login:** Deaktivert
- **Server-filer:** `/srv/synops/` (docker-compose.yml, .env, config/, data/)
- **Domener:**
  - `sidelinja.org` — Tenant-app (Sidelinja podcastredaksjonen)
  - `auth.sidelinja.org` — Authentik SSO
  - `git.sidelinja.org` — Forgejo (SSH port 222)
  - `vegard.info` — Separat nettsted
  - `synops.no` — Plattformdomene (placeholder, klar for subdomener)

## Git
- **Repos i Forgejo:**
  - `vegard/synops` — plattformkode og arkitektur: `ssh://git@git.sidelinja.org:222/vegard/synops.git`
  - `sidelinja/sidelinja` — podcastinnhold: `ssh://git@git.sidelinja.org:222/sidelinja/sidelinja.git`
- **Git-identitet:** vegard / vnotnes@pm.me
- **Forgejo-bruker:** vegard (admin)
- **CLI:** Bruk `tea`, ikke `gh` (vi bruker Forgejo, ikke GitHub)

## Viktige regler
- Aldri eksponere databaseporter mot internett
- All AI-trafikk via maskinrommet, aldri direkte til leverandør-APIer
- Tunge jobber (Whisper, LLM, TTS) blokkerer aldri brukerforespørsler
- Sjekk alltid relevant doc i `docs/` før implementering
- Dokumenter lærdommer i `docs/erfaringer/`

## Lagmodell
```
GUI (SvelteKit)
  │ skriv              │ les (sanntid, direkte WebSocket)
  ▼                    ▼
Maskinrommet (Rust)    SpacetimeDB ──→ GUI
  │
  ▼
Tjenester: PG+AGE, SpacetimeDB, CAS, Whisper, LiteLLM, LiveKit ...
```

## Kjerneprinsipper
1. **Alt er noder og edges.** Ingen separate tabeller for chat, kanban,
   kalender, notater. Visninger er spørringer mot grafen.
2. **Tre primitiver:** Input (fanger), Mottak (presenterer), Kommunikasjon
   (samler folk). Alt annet er visninger og edges.
3. **Maskinrommet orkestrerer alt.** Fang, prosesser, lever. Edge-drevet
   ressursallokering. Tjenester under er utbyttbare.
4. **Noder er sentrum.** Brukere, team, innhold — alt er noder.
   Du ser dine edges. Tilgang via materialisert tilgangsmatrise.
5. **Privat er default.** Input uten mottaker-edge er privat. Security
   by design, ikke konfigurasjon.
6. **PG er arkivet, SpacetimeDB er nåtid.** Ingen eierskapskonflikt.
   To lag, to roller.