server/docs/erfaringer/adapter_moenster.md

Erfaring: Adapter-mønster for chat (PG ↔ SpacetimeDB)

1. Mønsteret

Et felles interface (ChatConnection) med to implementasjoner:

• SpacetimeDB-adapter (primær) — all data fra SpacetimeDB, worker håndterer warmup + sync
• PG-adapter (fallback) — polling hvert 3 sek, brukes kun når SpacetimeDB ikke er konfigurert

Factory-funksjon velger adapter basert på miljøvariabel (VITE_SPACETIMEDB_URL).

ChatBlock.svelte  →  createChat()  →  SpacetimeDB-adapter (primær)
                                    →  PG-adapter (fallback, readonly)

Fordeler:

• Kan teste PG-adapter isolert uten Docker/SpacetimeDB
• Fallback er trivielt — fjern env-variabelen
• Komponenten vet ingenting om hvilken adapter som brukes
• ChatConnection-interface har edit(), delete(), react() — ingen direkte PG API-kall fra komponenten

Referanse: web/src/lib/chat/ — hele mappen er organisert etter dette mønsteret.

2. Historisk anti-pattern: Lazy wrapper som byttet adapter

Vi prøvde først en "lazy wrapper" som startet med PG-adapter og byttet til SpacetimeDB-adapter når tilkoblingen var klar. Problemet:

• En plain let activeConnection i wrapperen er ikke reaktiv i Svelte 5
• Når wrapperen byttet adapter, forsvant meldingene — ny adapter startet med tom liste
• Svelte-komponentene så aldri byttet fordi proxy-referansen ikke oppdaterte seg

Lærdom: Ikke bytt adapter runtime. Velg én ved oppstart.

3. Historisk anti-pattern: Hybrid-adapter (PG + SpacetimeDB samtidig)

Den andre iterasjonen brukte en hybrid-adapter som hentet historikk fra PG via REST og lyttet på SpacetimeDB for nye meldinger. Dette skapte:

• Kompleks dedup-logikk (deletedIds Set, merge av PG- og ST-meldinger)
• Race conditions mellom PG-polling og SpacetimeDB-callbacks
• BigInt-konverteringer og workarounds i frontend

Løsningen: SpacetimeDB som cache foran PG. Worker gjør warmup (PG → ST) ved oppstart, frontend snakker kun med SpacetimeDB. Ingen merge-logikk nødvendig.

4. Nåværende arkitektur

SpacetimeDB er en varm cache foran PostgreSQL:

• Worker warmup: Ved oppstart lastes meldinger + reaksjoner fra PG → SpacetimeDB per kanal
• Frontend → SpacetimeDB: Subscription gir alle meldinger (historikk fra warmup + nye)
• SpacetimeDB → PG: Sync-worker poller sync_outbox hvert sekund
• PG er autoritativ — ved SpacetimeDB-restart oppvarmes fra PG

Fordeler over hybrid:

• Ingen dedup, merge eller deletedIds
• Frontend-koden er dramatisk enklere
• Konsistent datamodell — alt kommer fra én kilde
• Reaksjoner håndteres via SpacetimeDB-tabeller, ikke PG API

5. Historisk anti-pattern: "PG-lekkasje" i SpacetimeDB-adapteren

Gjentatt feil (mars 2026, minst 3 iterasjoner): Når en ny feature trenger data som SpacetimeDB-modulen ikke har (metadata, edited_at, revisjoner), er det fristende å legge til en enrichFromPg()-funksjon som henter fra PG direkte. Dette bryter hele poenget med caching-laget.

Symptomer:

• SpacetimeDB-adapteren har fetch('/api/messages/...') kall
• Worker skriver til PG først, SpacetimeDB er "best-effort"
• Etter AI-vask vises ikke metadata/revisjoner fordi de bare finnes i PG
• Race conditions mellom SpacetimeDB-oppdateringer og PG-fetch

Hvorfor det skjer: Det er raskere å lage en PG API-rute enn å utvide SpacetimeDB-modulen (Rust compile, publish, regenerer bindings). Men det skaper teknisk gjeld som akkumulerer og undergraver hele arkitekturen.

Riktig løsning når SpacetimeDB mangler et felt:

1. Legg til feltet i SpacetimeDB Rust-modul (spacetimedb/src/lib.rs)
2. Utvid warmup til å laste feltet fra PG
3. Utvid sync til å persistere feltet til PG
4. Worker skriver til SpacetimeDB via reducer
5. Frontend leser kun fra SpacetimeDB

Aldri: Legg til fetch('/api/.../metadata') i SpacetimeDB-adapteren.

6. Anbefaling for neste komponent

Når Kanban eller Whiteboard skal bygges med SpacetimeDB:

1. Start med PG-adapter. Få hele flyten til å fungere med REST/polling først.
2. Lag SpacetimeDB-adapter med warmup. Worker laster data fra PG ved oppstart.
3. Bruk samme factory-mønster. Felles interface, env-variabel for valg.
4. Legg til warmup-config i channels.config (eller tilsvarende config-felt).
5. Test begge adaptere uavhengig før du integrerer i UI-komponenten.
6. Sjekk at alle felter frontend trenger finnes i SpacetimeDB-modulen før du implementerer adapteren. Utvid modulen først hvis nødvendig.