vegard
61b35d3c01
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>
81 lines
4.1 KiB
Markdown
81 lines
4.1 KiB
Markdown
# 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`).
|