From 0d0fd034151edb5cd3f3ef400c64687cec7264f0 Mon Sep 17 00:00:00 2001 From: vegard Date: Tue, 17 Mar 2026 12:23:10 +0100 Subject: [PATCH] Oppdater api_grensesnitt.md til maskinrommet-arkitekturen MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Det gamle dokumentet beskrev en v1-arkitektur der SvelteKit var web-API og Rust kun var workers. Med maskinrommet-retningen (besluttet) er Rust en axum HTTP API-server som mottar intensjoner fra frontend og eier alle skrivinger. Dokumentet er omskrevet til å reflektere dette. Co-Authored-By: Claude Opus 4.6 --- docs/infra/api_grensesnitt.md | 141 ++++++++++++++++------------------ 1 file changed, 68 insertions(+), 73 deletions(-) diff --git a/docs/infra/api_grensesnitt.md b/docs/infra/api_grensesnitt.md index 8f25c72..49a8836 100644 --- a/docs/infra/api_grensesnitt.md +++ b/docs/infra/api_grensesnitt.md @@ -1,73 +1,68 @@ -# Infrastruktur: API-grensesnitt og Tjenesteansvar -**Filsti:** `docs/infra/api_grensesnitt.md` - -## 1. Konsept -Definerer hvordan SvelteKit-frontenden kommuniserer med backend-tjenestene. Prinsippet er: **SvelteKit er web-serveren, Rust er workeren.** Ingen separat Rust HTTP API. - -## 2. Kommunikasjonskart - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Brukerens nettleser (SvelteKit klient) │ -└──────────┬──────────────────────┬───────────────────────────┘ - │ │ - │ WebSocket │ HTTP (forms, fetch) - ▼ ▼ -┌──────────────────┐ ┌─────────────────────────────────────┐ -│ SpacetimeDB │ │ SvelteKit Server │ -│ │ │ (load functions, form actions, │ -│ - Chat │ │ API routes) │ -│ - Kanban │ │ │ -│ - Live events │ │ Ansvar: │ -│ - Autocomplete │ │ - Les/skriv PostgreSQL direkte │ -│ - Studio- │ │ - Opprett jobber i job_queue │ -│ markører │ │ - Filopplasting (streaming) │ -│ │ │ - RSS-generering │ -│ │ │ - Kunnskapsgraf-spørringer │ -└──────────────────┘ └──────────────┬───────────────────────┘ - │ - │ SQL - ▼ - ┌──────────────────────────┐ - │ PostgreSQL │ - │ │ - │ - Kunnskapsgraf │ - │ - Episodemetadata │ - │ - Statistikk │ - │ - Jobbkø (job_queue) │ - │ - Brukerdata │ - └──────────────┬────────────┘ - │ - │ Poll (SELECT FOR UPDATE) - ▼ - ┌──────────────────────────┐ - │ Rust Workers │ - │ │ - │ - whisper_transcribe │ - │ - openrouter_analyze │ - │ - research_clip │ - │ - stats_parse │ - │ - sync_to_pg (SpaceDB→PG)│ - └──────────────────────────┘ -``` - -## 3. Ansvarsfordeling - -| Komponent | Rolle | Snakker med | -|---|---|---| -| **SvelteKit (klient)** | UI, brukerinteraksjon | SpacetimeDB (WS), SvelteKit server (HTTP) | -| **SvelteKit (server)** | Web-API, PG-tilgang, jobb-trigger | PostgreSQL (SQL) | -| **SpacetimeDB** | Sanntids state, push til klienter | Klienter (WS), sync-worker (intern) | -| **Rust Workers** | Tunge bakgrunnsjobber, synk | PostgreSQL (SQL), SpacetimeDB, OpenRouter, faster-whisper | - -## 4. Viktige avklaringer -- **Rust er ikke en API-server.** Rust kjører kun som workers/prosessorer som poller jobbkøen -- **SvelteKit server-side er trygt.** Load functions og form actions kjører på serveren og kan snakke direkte med PG uten sikkerhetsproblemer -- **Filopplasting** håndteres av SvelteKit (streaming for store filer), som lagrer filen på disk og oppretter en jobb i køen -- **SpacetimeDB nås aldri via SvelteKit server** — kun direkte fra klienten via WebSocket - -## 5. Instruks for Claude Code -- Ikke opprett et separat Rust HTTP API/webserver-prosjekt -- Bruk SvelteKit `+server.ts` (API routes) eller `+page.server.ts` (form actions/load) for all HTTP-kommunikasjon -- Rust-kode skal struktureres som worker-binærer som konsumerer fra `job_queue` -- For PG-tilgang i SvelteKit, bruk et bibliotek som `postgres.js` eller `drizzle-orm` +# Infrastruktur: API-grensesnitt og Tjenesteansvar + +## 1. Konsept + +Frontend sender **intensjoner** til maskinrommet (Rust/axum HTTP API). +Maskinrommet eier alle skrivinger: det validerer, skriver til SpacetimeDB +(instant), persisterer til PG (asynk), og orkestrerer konsekvenser. + +Lesestien for sanntid går direkte fra SpacetimeDB til frontend via WebSocket. +Tunge spørringer (søk, statistikk, graftraversering) går via maskinrommet → PG. + +## 2. Kommunikasjonskart + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Brukerens nettleser (SvelteKit klient) │ +└──────────┬──────────────────────┬───────────────────────────┘ + │ │ + │ HTTP (intensjoner) │ WebSocket (sanntid) + ▼ ▼ +┌──────────────────────┐ ┌──────────────────┐ +│ Maskinrommet (Rust) │ │ SpacetimeDB │ +│ axum HTTP API │ │ │ +│ │ │ - Hele grafen │ +│ Ansvar: │ │ - Push til │ +│ - Validere │ │ klienter │ +│ - Skrive STDB+PG │ │ │ +│ - Orkestrere │ └──────────────────┘ +│ - Tunge spørringer │ +│ - Bakgrunnsjobber │ +└──┬─────┬─────┬───────┘ + │ │ │ + ▼ ▼ ▼ +┌─────┐┌─────┐┌─────────────┐ +│ PG ││STDB ││ Whisper, │ +│ ││ ││ LiteLLM, │ +│ ││ ││ LiveKit ... │ +└─────┘└─────┘└─────────────┘ +``` + +## 3. Ansvarsfordeling + +| Komponent | Rolle | Snakker med | +|---|---|---| +| **SvelteKit (klient)** | UI, brukerinteraksjon | Maskinrommet (HTTP), SpacetimeDB (WS) | +| **Maskinrommet (Rust)** | Intensjons-API, orkestrering, tunge spørringer | PG, SpacetimeDB, CAS, Whisper, LiteLLM | +| **SpacetimeDB** | Sanntids state, push til klienter | Klienter (WS), maskinrommet (skriver) | +| **PostgreSQL** | Persistent arkiv, søk, statistikk | Maskinrommet (SQL) | + +## 4. Viktige avklaringer + +- **Maskinrommet er en HTTP API-server** (axum). Frontend sender intensjoner hit. +- **Maskinrommet eier alle skrivinger.** Frontend skriver aldri direkte til PG eller STDB. +- **SpacetimeDB nås direkte** fra klienten via WebSocket for lesing (sanntid). +- **SvelteKit er et rent frontend-prosjekt.** Ingen server-side PG-tilgang. +- **Bakgrunnsjobber** (Whisper, LLM, TTS) orkestreres av maskinrommet, aldri direkte fra frontend. + +## 5. Instruks for Claude Code + +- Maskinrommet (`maskinrommet/`) er Rust-prosjektet med axum, tokio, sqlx. +- Intensjoner fra frontend → `POST /intentions/*` endepunkter i maskinrommet. +- Tunge spørringer fra frontend → `GET /query/*` endepunkter i maskinrommet. +- Frontend (SvelteKit) har ingen direkte databasetilgang. +- Bakgrunnsjobber trigges av maskinrommet, ikke via en separat jobbkø-tabell. + +> **Historisk merknad:** Tidligere beskrev dette dokumentet en arkitektur +> der SvelteKit var web-API og Rust kun var workers. Denne ble erstattet +> av maskinrommet-arkitekturen (se `docs/retninger/maskinrommet.md`).