vegard 61b35d3c01 Skrivestien: POST /intentions/create_node (oppgave 2.4)

Implementerer den første intensjonen i maskinrommet — skrivestien
som gjør at frontend kan opprette noder via maskinrommet.

Flyten:
1. Valider input (node_kind, visibility, metadata)
2. Generer UUIDv7 (tidssortert)
3. Skriv til SpacetimeDB (instant — frontend ser noden umiddelbart)
4. Spawn async tokio-task for PG-persistering
5. Returner node_id uten å vente på PG

Verifisert på server med fire testcaser:
1. Uten auth → 401
2. Ugyldig visibility → 400 med feilmelding
3. Minimal request (tomt body) → 200, node opprettet med defaults
4. Full request → 200, node verifisert i både STDB og PG

Også: Dockerfile oppdatert til Rust 1.88 (avhengigheter krevde >1.86),
og api_grensesnitt.md oppdatert med endepunktdokumentasjon.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-17 13:09:50 +01:00

4.1 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. Implementerte endepunkter

Offentlige

GET /health — Helsesjekk. Verifiserer PG- og STDB-tilkobling.

Autentiserte (krever `Authorization: Bearer <JWT>`)

GET /me — Returnerer autentisert brukers node_id og authentik_sub.
POST /intentions/create_node — Opprett node. Skriv til STDB (instant), spawn async PG-skriving, returner node_id umiddelbart.
- Body (JSON): { node_kind?, title?, content?, visibility?, metadata? }
- Defaults: node_kind="content", visibility="hidden", andre felter tomme
- Respons: { node_id: "<uuid>" }

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

4.1 KiB Raw Blame History