From be1b6caa29af7d4deec806c28fe3727e13578cdf Mon Sep 17 00:00:00 2001 From: vegard Date: Wed, 18 Mar 2026 01:56:51 +0000 Subject: [PATCH] Oppdater CLAUDE.md og arkitektur med nye prinsipper MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Maskinrommet orkestrerer, CLI-verktøy gjør jobben - Spatial canvas med drag-and-drop som primær interaksjon - To retninger: dra ut = ny node, dra inn = transformer - Arbeidsflaten er en node (rekursivt) - Caddy flyttet til native i teknologitabellen - CLI-verktøy lagt til i lagmodell og teknologivalg Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 21 +++++++++-- docs/arkitektur.md | 91 ++++++++++++++++++++++++++++++++-------------- 2 files changed, 82 insertions(+), 30 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 220a404..1831b36 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -159,10 +159,13 @@ Ref: `docs/infra/agent_api.md` for planlagt API-overflate. ## Lagmodell ``` -GUI (SvelteKit) +GUI (SvelteKit) — spatial canvas med verktøy-paneler │ skriv │ les (sanntid, direkte WebSocket) ▼ ▼ Maskinrommet (Rust) SpacetimeDB ──→ GUI + │ orkestrerer + ▼ +CLI-verktøy (tools/) ←── Claude bruker de samme │ ▼ Tjenester: PG+AGE, SpacetimeDB, CAS, Whisper, LiteLLM, LiveKit ... @@ -173,11 +176,23 @@ Tjenester: PG+AGE, SpacetimeDB, CAS, Whisper, LiteLLM, LiveKit ... kalender, notater. Visninger er spørringer mot grafen. 2. **Tre primitiver:** Input (fanger), Mottak (presenterer), Kommunikasjon (samler folk). Alt annet er visninger og edges. -3. **Maskinrommet orkestrerer alt.** Fang, prosesser, lever. Edge-drevet - ressursallokering. Tjenester under er utbyttbare. +3. **Maskinrommet orkestrerer, CLI-verktøy gjør jobben.** Maskinrommet eier + auth, intentions, jobbkø og edge-logikk. All prosessering (transkribering, + rendering, AI, lyd) skjer i CLI-verktøy som maskinrommet spawner. + Claude bruker de samme verktøyene direkte. Ny funksjonalitet starter + som CLI-verktøy, absorberes i orkestratoren, dokumenteres nøye. + Ref: `docs/retninger/unix_filosofi.md`. 4. **Noder er sentrum.** Brukere, team, innhold — alt er noder. Du ser dine edges. Tilgang via materialisert tilgangsmatrise. 5. **Privat er default.** Input uten mottaker-edge er privat. Security by design, ikke konfigurasjon. 6. **PG er arkivet, SpacetimeDB er nåtid.** Ingen eierskapskonflikt. To lag, to roller. +7. **Alt er paneler i en arbeidsflate.** Brukergrensesnittet er et spatial + canvas der verktøy plasseres, sizes og arrangeres fritt. Hver feature + er et panel i BlockShell. Interaksjon mellom paneler via drag-and-drop: + - **Dra ut av kontekst → ny node.** Innhold som dras fra et verktøy + til et annet skaper en ny node med `source_material`-edge tilbake. + - **Dra verktøy inn i kontekst → transformer.** Et verktøy (AI, editor, + studio) som mottar en node anvender sin funksjon på originalen. + Ref: `docs/retninger/arbeidsflaten.md`, `docs/features/universell_overfoering.md`. diff --git a/docs/arkitektur.md b/docs/arkitektur.md index 2c00886..ea42b02 100644 --- a/docs/arkitektur.md +++ b/docs/arkitektur.md @@ -15,25 +15,26 @@ lag som leser grafen fra SpacetimeDB. ## Lagmodell ``` -┌─────────────────────────────────────┐ -│ GUI (SvelteKit) │ -│ Visninger: spørringer mot STDB │ -└────────┬──────────────────┬─────────┘ +┌─────────────────────────────────────────┐ +│ GUI (SvelteKit) — spatial canvas │ +│ Verktøy-paneler i BlockShell │ +│ Drag-and-drop mellom paneler │ +└────────┬──────────────────┬─────────────┘ │ intensjoner │ les (sanntid) │ │ direkte WebSocket ┌────────▼────────┐ ┌──────▼──────────┐ │ Maskinrommet │ │ SpacetimeDB │ │ (Rust) │ │ Hele grafen │ -│ Eier alle │ │ (noder+edges) │ -│ skrivinger │ └─────────────────┘ -└──┬─────┬─────┬──┘ - │ │ │ - ▼ ▼ ▼ -┌─────┐┌─────┐┌─────┐┌─────────────┐ -│ PG ││STDB ││ CAS ││ Whisper, │ -│(bak)││(skr)││ ││ LiteLLM, │ -│ ││ ││ ││ LiveKit ... │ -└─────┘└─────┘└─────┘└─────────────┘ +│ Orkestrerer │ │ (noder+edges) │ +└──┬───────────┬──┘ └─────────────────┘ + │ spawner │ + ▼ ▼ +┌─────────┐ ┌─────┐┌─────┐┌─────────────┐ +│ CLI- │ │ PG ││ CAS ││ Whisper, │ +│ verktøy │ │ ││ ││ LiteLLM, │ +│ (tools/)│ │ ││ ││ LiveKit ... │ +└─────────┘ └─────┘└─────┘└─────────────┘ + ▲ Claude bruker de samme ``` ### Skrivestien @@ -86,6 +87,32 @@ Visninger er spørringer mot SpacetimeDB med edge-filtre: Ingen forhåndsdefinerte visningstyper. Nye visninger er nye filtre. +## Arbeidsflaten — spatial canvas + +Brukergrensesnittet er et **spatial canvas** der verktøy (chat, kanban, +kalender, editor, studio) plasseres som paneler i en fri flate. + +### Tre lag +1. **Personlig flate** — brukerens standard arbeidsflate +2. **Node-flate** — default-oppsett fra node-eier/traits +3. **Brukerens tilpasning** — overrides lagret per bruker per node + +### Drag-and-drop som primær interaksjon +To retninger, to semantikker: +- **Dra ut av kontekst → ny node.** Innhold som dras fra et verktøy + til et annet skaper en ny node med `source_material`-edge tilbake + til originalen. Originalen er uendret. +- **Dra verktøy inn i kontekst → transformer.** Et verktøy (AI, editor) + som mottar en node anvender sin funksjon direkte på originalen. + +Kompatibilitetsmatrisen bestemmer hva som kan dras hvor. +Ref: `docs/retninger/arbeidsflaten.md`, `docs/features/universell_overfoering.md` + +### Arbeidsflaten er en node +Canvaset er selv en node med edges til panelene det viser. Layout +(posisjon, størrelse, z-index) er metadata på edgen. Arbeidsflater +kan nestes — en flate kan vises som panel i en annen. + ## Input Én universell input-komponent, gjenbrukt overalt. Fanger tekst, lyd, @@ -104,14 +131,23 @@ system-edges som er usynlige for traversering. ## Maskinrommet -Rust-tjeneste med tre operasjoner: **fang**, **prosesser**, **lever**. +Rust-tjeneste som **orkestrerer**, ikke gjør arbeid selv. Eier alle skrivinger. Frontend sender intensjoner, maskinrommet -validerer og utfører. Edge-drevet ressursorkestrering: maskinrommet -leser edges og bestemmer hvilke tjenester som spinnes opp. +validerer og utfører. Selve prosesseringen delegeres til CLI-verktøy +i `tools/` — maskinrommet spawner riktig verktøy fra jobbkøen. -Forvalter også CAS (binærlagring) med intelligent pruning basert -på modalitet, edges og aksessmønstre. +Kjerneansvar (forblir i maskinrommet): +- Auth + tilgangskontroll +- Intentions (validering, edge-logikk, STDB+PG-skriving) +- Jobbkø (polling, retry, dead letter) +- CAS-forvaltning og pruning + +Alt annet (transkribering, rendering, AI, lyd, RSS) er CLI-verktøy. +Claude bruker de samme verktøyene direkte fra terminalen — nyttig +for debugging, testing og utvikling. + +Ref: `docs/retninger/unix_filosofi.md` ## Sikkerhet @@ -156,19 +192,20 @@ Egenutviklet kode kjører **native på hosten** via systemd. Tredjepartstjenester kjører i **Docker**. Prinsipp: Docker for det vi ikke bygger selv, native for det vi har full kontroll over. -**Native (systemd):** maskinrommet (Rust), SvelteKit (når klar). -**Docker:** PostgreSQL, SpacetimeDB, Authentik, Caddy, LiteLLM, faster-whisper. +**Native (systemd):** Caddy, maskinrommet (Rust), SvelteKit. +**Docker:** PostgreSQL, SpacetimeDB, Authentik, LiteLLM, faster-whisper. -Maskinrommet kjører native fordi det trenger tilgang til `claude` CLI -og hele vertsmaskinens verktøy. Caddy (Docker) når maskinrommet via -`host.docker.internal`. +Maskinrommet og Caddy kjører native fordi de trenger direkte tilgang +til host-ressurser (CLI-verktøy, TLS-konfig). Docker-tjenester +eksponerer porter på localhost. ## Teknologivalg | Rolle | Teknologi | Kjøremodus | Begrunnelse | |-------|-----------|------------|-------------| -| Orkestrator | Rust | Native (systemd) | Ytelse, typesikkerhet, eier alle skrivinger, trenger host-tilgang | -| Frontend | SvelteKit | Native (systemd) | PWA, SSR, tynt lag mot STDB | +| Orkestrator | Rust | Native (systemd) | Orkestrerer CLI-verktøy, eier auth+edges, trenger host-tilgang | +| CLI-verktøy | Rust/Shell | Native | Prosessering (transcribe, render, audio, AI). Delt mellom maskinrommet og Claude | +| Frontend | SvelteKit | Native (systemd) | PWA, SSR, spatial canvas med verktøy-paneler | | Database | PostgreSQL | Docker | Versjonsstyring, enkel oppgradering | | Sanntid | SpacetimeDB | Docker | Eksperimentelt, offisielt image | | Binærlagring | CAS (filsystem) | Native | Enkel, deduplisering, ingen ekstern avhengighet | @@ -177,7 +214,7 @@ og hele vertsmaskinens verktøy. Caddy (Docker) når maskinrommet via | STT | faster-whisper | Docker | Modellhåndtering, ferdig image | | TTS | ElevenLabs (→ lokal) | — | Kommersiell start, lokal når kvaliteten holder | | Auth | Authentik | Docker | Kompleks stack (server + worker + Redis) | -| Reverse proxy | Caddy | Docker | Auto-TLS, kan tas native senere | +| Reverse proxy | Caddy | Native (systemd) | Auto-TLS, direkte tilgang til konfig | | Lyd/video | LiveKit | Docker | WebRTC, self-hosted | ## Traits — samlingsnoder med evner