vegard 0d0fd03415 Oppdater api_grensesnitt.md til maskinrommet-arkitekturen

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 <noreply@anthropic.com>

2026-03-17 12:23:10 +01:00

3.6 KiB

Raw Blame History

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).

3.6 KiB Raw Blame History