synops/docs/features/kunnskapsgraf_og_relasjoner.md

Feature Spec: Kunnskapsgraf og Relasjoner (Logseq-modell)

Filsti: docs/features/kunnskapsgraf_og_relasjoner.md

1. Konsept

Inspirert av verktøy som Logseq og Obsidian, bygger vi databasen som en toveis-lenket graf. Målet er å skape "serendipity" (lykketreff) i research-fasen ved å synliggjøre uventede forbindelser. Hvis Aktør A og Aktør B begge er nevnt i samme chat-tråd eller knyttet til samme Tema over tid, skal systemet kunne visualisere denne røde tråden for programlederne.

2. Arkitektur og Teknologivalg

Vi unngår tunge, dedikerte grafdatabaser (som Neo4j) for å holde infrastrukturen og ressursbruken (RAM) minimal.

• Valgt teknologi: Vanilla PostgreSQL.
• Mekanisme: En "Nodes and Edges" (Noder og Kanter) tabellstruktur kombinert med Recursive CTEs (Common Table Expressions) i SQL for å traversere grafen. Dette er mer enn raskt nok for redaksjonelle datamengder (100k+ noder).

3. Datastruktur

3.1 Supertabell: nodes

Alle entiteter i systemet arver sin UUID fra én sentral tabell. Dette gir ekte Foreign Key-integritet på graph_edges uten applikasjonslogikk-hacks.

CREATE TYPE node_type AS ENUM (
    'entitet',      -- person, organisasjon, sted, tema, konsept (erstatter 'aktør' og 'tema')
    'episode',      -- podcast-episode
    'segment',      -- tidsavgrenset del av episode
    'melding',      -- meldingsboks (chat, kanban-kort, kalenderhendelse, faktoide, notat)
    'channel',      -- gruppering av meldinger
    'kanban_board', -- strukturelt
    'calendar',     -- strukturelt
    'meeting'       -- LiveKit-møte
);

CREATE TABLE nodes (
    id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    workspace_id UUID NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
    node_type    node_type NOT NULL,
    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);

Merk: Gamle enum-verdier ('aktør', 'tema', 'faktoide', 'note', 'kanban_card', 'calendar_event') kan ikke fjernes fra PostgreSQL ENUM, men skal aldri brukes i ny kode.

3.2 Detailtabeller

Hver nodetype har sin egen tabell med FK til nodes.

Entiteter (erstatter actors og topics)

Alt som kan nevnes med # i chat er en entitet — personer, organisasjoner, steder, temaer, konsepter. Én tabell, én autocomplete, én #-mekanisme.

CREATE TABLE entities (
    id        UUID PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
    name      TEXT NOT NULL,             -- Autoritativ skrivemåte
    type      TEXT NOT NULL,             -- 'person', 'organisasjon', 'sted', 'tema', 'konsept'
    aliases   TEXT[] DEFAULT '{}',       -- Forkortelser, kallenavn, vanlige feilstavinger
    avatar_url TEXT                      -- Portrett, flagg, logo, kommunevåpen
);

CREATE INDEX idx_entities_name ON entities(name);
CREATE INDEX idx_entities_aliases ON entities USING GIN(aliases);

Autocomplete søker i både name og aliases. name er den autoritative formen som vises i UI. Eksempler:

• name: 'Jonas Gahr Støre', aliases: {'JGS', 'Støre'}, type: 'person'
• name: 'Arbeiderpartiet', aliases: {'AP', 'Ap', 'DNA'}, type: 'organisasjon'
• name: 'Lørenskog', aliases: {'Lørenskog kommune'}, type: 'sted'
• name: 'Skolepolitikk', aliases: {}, type: 'tema'

Episoder og segmenter

CREATE TABLE episodes (
    id           UUID PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
    title        TEXT NOT NULL,
    published_at TIMESTAMPTZ,
    guid         TEXT UNIQUE NOT NULL  -- RSS <guid>, aldri endres
);

CREATE TABLE segments (
    id          UUID PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
    episode_id  UUID NOT NULL REFERENCES episodes(id) ON DELETE CASCADE,
    start_time  INTERVAL NOT NULL,
    end_time    INTERVAL NOT NULL,
    transcript  TEXT,          -- Segmentets transkripsjon
    CONSTRAINT valid_timerange CHECK (end_time > start_time)
);

CREATE INDEX idx_segments_episode ON segments(episode_id);
CREATE INDEX idx_segments_transcript_fts ON segments USING GIN (to_tsvector('norwegian', transcript));

3.3 Kantene: graph_edges

All kobling skjer i én sentral tabell med ekte FK-integritet. workspace_id er denormalisert fra nodes for å muliggjøre RLS direkte på edges:

CREATE TABLE graph_edges (
    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    workspace_id  UUID NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
    source_id     UUID NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
    target_id     UUID NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
    relation_type TEXT NOT NULL,  -- 'MENTIONS', 'CONTRADICTS', 'WORKS_FOR', 'PART_OF', 'DISCUSSED_IN'
    context_id    UUID REFERENCES nodes(id) ON DELETE SET NULL,
    confidence    REAL CHECK (confidence BETWEEN 0.0 AND 1.0),
    created_by    TEXT REFERENCES users(authentik_id) ON DELETE SET NULL,
    origin        TEXT NOT NULL DEFAULT 'system',  -- 'system', 'user', 'ai'
    created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
    CONSTRAINT no_self_reference CHECK (source_id != target_id),
    CONSTRAINT unique_edge UNIQUE (source_id, target_id, relation_type)
);

CREATE INDEX idx_edges_source ON graph_edges(source_id);
CREATE INDEX idx_edges_target ON graph_edges(target_id);
CREATE INDEX idx_edges_relation ON graph_edges(relation_type);
CREATE INDEX idx_edges_workspace ON graph_edges(workspace_id);

Merk: UNIQUE(source_id, target_id, relation_type) forhindrer duplikate relasjoner. Bruk ON CONFLICT DO NOTHING eller ON CONFLICT DO UPDATE SET confidence = ... ved upsert.

Merk: node_type-enumet kan utvides av feature-spesifikke migrasjoner (f.eks. valgomat_question, valgomat_axis). Se docs/concepts/valgomaten.md for eksempel.

4. Segmenter og Transkripsjoner

4.1 Segment som grafnode

Episoder deles i segmenter — tidsavgrensede deler med egen transkripsjon. Hvert segment er en node i grafen og kan kobles til Temaer, Aktører og Faktoider. Dette muliggjør presise oppslag som: "I Episode 42, fra 14:23 til 21:07, diskuterte dere Skolepolitikk og sa følgende..."

Episode 42 (node: episode)
  ├── Segment 00:00-14:22 (node: segment) ──DISCUSSED_IN──► Tema: Mediepolitikk
  ├── Segment 14:23-21:07 (node: segment) ──DISCUSSED_IN──► Tema: Skolepolitikk
  │                                        ──MENTIONS──────► Aktør: Støre
  └── Segment 21:08-45:00 (node: segment) ──DISCUSSED_IN──► Tema: Kommuneøkonomi

Kapitler i RSS-feeden genereres fra segmentene, men er et eget konsern (se docs/concepts/podcastfabrikken.md).

4.2 Transkripsjoner: Git som master, PG som søkeindeks

Transkripsjoner lever i to steder med klart eierskap:

Sted	Rolle	Format
Git (Forgejo)	Kilde til sannhet. Redigerbar, sporbar, diffbar	Markdown med tidsstempler
PostgreSQL	Søkeindeks. Full-text search, koblet til grafen	Segmentert i segments-tabellen

Flyt:

Whisper → Git (rå transkripsjon med tidsstempler)
            → Redaksjonen korrigerer manuelt ved behov
            → Push til Forgejo
            → Forgejo webhook trigger 'transcript_reimport'-jobb i jobbkøen
            → Rust-worker parser filen, splitter i segmenter
            → DELETE + INSERT i én PG-transaksjon (idempotent reimport)
            → Grafkoblinger bevares (segment-UUID deterministisk fra episode-UUID + tidsstempel)

Deterministisk UUID for segmenter: UUID = uuid_v5(episode_uuid, start_time_ms). Dette sikrer at samme segment alltid får samme UUID, selv ved reimport. Grafkoblinger som peker på segmentet overlever dermed en full reimport.

5. Arbeidsflyt: Hvordan grafen vokser

Grafen bygger seg opp organisk gjennom daglig bruk av Sidelinja-suiten:

1. Chat & Notater: En bruker skriver: "Apropos #Hans_Petter_Sjøli, hva var greia med #Arbeiderpartiet?"
2. Parsing (Svelte/Rust): Systemet fanger opp de to #-taggene (som allerede har UUIDs i Aktør-tabellen).
3. Edge Creation: SvelteKit server-side oppretter automatisk to nye oppføringer i graph_edges-tabellen:
   • [Melding UUID] -> MENTIONS -> [Sjøli UUID]
   • [Melding UUID] -> MENTIONS -> [Arbeiderpartiet UUID]
4. Indirekte relasjon: Fordi begge aktørene nå deler samme context_id (meldingen), vet Kunnskapsgrafen at det finnes en tematisk kobling mellom Sjøli og Ap.
5. Publisering: Når en episode publiseres, kobles segmentene automatisk til relevante Temaer og Aktører basert på AI-analyse av transkripsjonen.

6. Instruks for Claude Code

• Workspace-isolasjon: Alle noder tilhører en workspace. Opprett alltid noder med riktig workspace_id. Spørringer mot detailtabeller (actors, topics, etc.) filtrerer alltid via JOIN med nodes.
• nodes-tabellen er obligatorisk. Opprett alltid en rad i nodes før du inserter i en detailtabell. Bruk en hjelpefunksjon som gjør begge i én transaksjon.
• graph_edges krever workspace_id. Ved opprettelse av edges, sett workspace_id fra kilde-noden. UNIQUE(source_id, target_id, relation_type) hindrer duplikater — bruk ON CONFLICT ved upsert.
• Graf-spørringer: Bruk WITH RECURSIVE i PostgreSQL når du bygger endepunkter som skal hente ut "Linked Mentions" eller nettverket rundt en spesifikk Aktør opp til 2-3 ledd ut.
• Fremtidssikring for UI: Design JSON-responsen slik at den lett kan mates inn i graf-visualiseringsbiblioteker (som D3.js eller Vis.js) i Svelte-frontenden. Formatet bør være { "nodes": [...], "edges": [...] }.
• Transkripsjon-reimport: Workeren må være idempotent. Bruk uuid_v5(episode_uuid, start_time_ms) for deterministiske segment-UUIDs. Slett og gjenopprett segmenter i én transaksjon, men ikke slett edges som peker til segmentene — de overlever fordi UUID-en er stabil. Merk: Hvis manuelle korrigeringer endrer segment-grenser (start_time), endres UUID-en. Løsning: automatisk flytt eksisterende edges til nærmeste nye segment basert på tidsintervall-overlapp.
• Full-text search: Bruk to_tsvector('norwegian', transcript) for norsk språkstøtte i søk.