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