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>
This commit is contained in:
parent
b35eb100fa
commit
0d0fd03415
1 changed files with 68 additions and 73 deletions
|
|
@ -1,73 +1,68 @@
|
||||||
# Infrastruktur: API-grensesnitt og Tjenesteansvar
|
# Infrastruktur: API-grensesnitt og Tjenesteansvar
|
||||||
**Filsti:** `docs/infra/api_grensesnitt.md`
|
|
||||||
|
## 1. Konsept
|
||||||
## 1. Konsept
|
|
||||||
Definerer hvordan SvelteKit-frontenden kommuniserer med backend-tjenestene. Prinsippet er: **SvelteKit er web-serveren, Rust er workeren.** Ingen separat Rust HTTP API.
|
Frontend sender **intensjoner** til maskinrommet (Rust/axum HTTP API).
|
||||||
|
Maskinrommet eier alle skrivinger: det validerer, skriver til SpacetimeDB
|
||||||
## 2. Kommunikasjonskart
|
(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.
|
||||||
│ Brukerens nettleser (SvelteKit klient) │
|
|
||||||
└──────────┬──────────────────────┬───────────────────────────┘
|
## 2. Kommunikasjonskart
|
||||||
│ │
|
|
||||||
│ WebSocket │ HTTP (forms, fetch)
|
```
|
||||||
▼ ▼
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
┌──────────────────┐ ┌─────────────────────────────────────┐
|
│ Brukerens nettleser (SvelteKit klient) │
|
||||||
│ SpacetimeDB │ │ SvelteKit Server │
|
└──────────┬──────────────────────┬───────────────────────────┘
|
||||||
│ │ │ (load functions, form actions, │
|
│ │
|
||||||
│ - Chat │ │ API routes) │
|
│ HTTP (intensjoner) │ WebSocket (sanntid)
|
||||||
│ - Kanban │ │ │
|
▼ ▼
|
||||||
│ - Live events │ │ Ansvar: │
|
┌──────────────────────┐ ┌──────────────────┐
|
||||||
│ - Autocomplete │ │ - Les/skriv PostgreSQL direkte │
|
│ Maskinrommet (Rust) │ │ SpacetimeDB │
|
||||||
│ - Studio- │ │ - Opprett jobber i job_queue │
|
│ axum HTTP API │ │ │
|
||||||
│ markører │ │ - Filopplasting (streaming) │
|
│ │ │ - Hele grafen │
|
||||||
│ │ │ - RSS-generering │
|
│ Ansvar: │ │ - Push til │
|
||||||
│ │ │ - Kunnskapsgraf-spørringer │
|
│ - Validere │ │ klienter │
|
||||||
└──────────────────┘ └──────────────┬───────────────────────┘
|
│ - Skrive STDB+PG │ │ │
|
||||||
│
|
│ - Orkestrere │ └──────────────────┘
|
||||||
│ SQL
|
│ - Tunge spørringer │
|
||||||
▼
|
│ - Bakgrunnsjobber │
|
||||||
┌──────────────────────────┐
|
└──┬─────┬─────┬───────┘
|
||||||
│ PostgreSQL │
|
│ │ │
|
||||||
│ │
|
▼ ▼ ▼
|
||||||
│ - Kunnskapsgraf │
|
┌─────┐┌─────┐┌─────────────┐
|
||||||
│ - Episodemetadata │
|
│ PG ││STDB ││ Whisper, │
|
||||||
│ - Statistikk │
|
│ ││ ││ LiteLLM, │
|
||||||
│ - Jobbkø (job_queue) │
|
│ ││ ││ LiveKit ... │
|
||||||
│ - Brukerdata │
|
└─────┘└─────┘└─────────────┘
|
||||||
└──────────────┬────────────┘
|
```
|
||||||
│
|
|
||||||
│ Poll (SELECT FOR UPDATE)
|
## 3. Ansvarsfordeling
|
||||||
▼
|
|
||||||
┌──────────────────────────┐
|
| Komponent | Rolle | Snakker med |
|
||||||
│ Rust Workers │
|
|---|---|---|
|
||||||
│ │
|
| **SvelteKit (klient)** | UI, brukerinteraksjon | Maskinrommet (HTTP), SpacetimeDB (WS) |
|
||||||
│ - whisper_transcribe │
|
| **Maskinrommet (Rust)** | Intensjons-API, orkestrering, tunge spørringer | PG, SpacetimeDB, CAS, Whisper, LiteLLM |
|
||||||
│ - openrouter_analyze │
|
| **SpacetimeDB** | Sanntids state, push til klienter | Klienter (WS), maskinrommet (skriver) |
|
||||||
│ - research_clip │
|
| **PostgreSQL** | Persistent arkiv, søk, statistikk | Maskinrommet (SQL) |
|
||||||
│ - stats_parse │
|
|
||||||
│ - sync_to_pg (SpaceDB→PG)│
|
## 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.
|
||||||
## 3. Ansvarsfordeling
|
- **SpacetimeDB nås direkte** fra klienten via WebSocket for lesing (sanntid).
|
||||||
|
- **SvelteKit er et rent frontend-prosjekt.** Ingen server-side PG-tilgang.
|
||||||
| Komponent | Rolle | Snakker med |
|
- **Bakgrunnsjobber** (Whisper, LLM, TTS) orkestreres av maskinrommet, aldri direkte fra frontend.
|
||||||
|---|---|---|
|
|
||||||
| **SvelteKit (klient)** | UI, brukerinteraksjon | SpacetimeDB (WS), SvelteKit server (HTTP) |
|
## 5. Instruks for Claude Code
|
||||||
| **SvelteKit (server)** | Web-API, PG-tilgang, jobb-trigger | PostgreSQL (SQL) |
|
|
||||||
| **SpacetimeDB** | Sanntids state, push til klienter | Klienter (WS), sync-worker (intern) |
|
- Maskinrommet (`maskinrommet/`) er Rust-prosjektet med axum, tokio, sqlx.
|
||||||
| **Rust Workers** | Tunge bakgrunnsjobber, synk | PostgreSQL (SQL), SpacetimeDB, OpenRouter, faster-whisper |
|
- Intensjoner fra frontend → `POST /intentions/*` endepunkter i maskinrommet.
|
||||||
|
- Tunge spørringer fra frontend → `GET /query/*` endepunkter i maskinrommet.
|
||||||
## 4. Viktige avklaringer
|
- Frontend (SvelteKit) har ingen direkte databasetilgang.
|
||||||
- **Rust er ikke en API-server.** Rust kjører kun som workers/prosessorer som poller jobbkøen
|
- Bakgrunnsjobber trigges av maskinrommet, ikke via en separat jobbkø-tabell.
|
||||||
- **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
|
> **Historisk merknad:** Tidligere beskrev dette dokumentet en arkitektur
|
||||||
- **SpacetimeDB nås aldri via SvelteKit server** — kun direkte fra klienten via WebSocket
|
> der SvelteKit var web-API og Rust kun var workers. Denne ble erstattet
|
||||||
|
> av maskinrommet-arkitekturen (se `docs/retninger/maskinrommet.md`).
|
||||||
## 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`
|
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue