vegard
fd0b75ee13
Orkestrering restrukturert med deklarativt script som primærnivå:
- Nivå 1: eksakte CLI-kall med {event.*}-variabler, ingen AI
- Nivå 2: fritekst tolket av bot med function calling
- Nivå 3: drømmemodus — bruker skriver fritt, mangler→work_items
- Auto-eskalering: script→bot ved uventet feil
Rename portvokter→vaktmester i alle docs — bedre navn for en
tjeneste som gjør ting, ikke bare sjekker legitimasjon.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
171 lines
5.8 KiB
Markdown
171 lines
5.8 KiB
Markdown
# Feature: Systemmanual (`synops-manual`)
|
|
|
|
## Konsept
|
|
|
|
`synops-manual` genererer en komplett teknisk instruksjonsmanual
|
|
for hele Synops. Manualen er selvforsynt — gitt en ren server og
|
|
dette dokumentet kan hele systemet bygges fra scratch.
|
|
|
|
## Hvorfor
|
|
|
|
- **Katastrofegjenoppbygging.** Serveren brenner. Du har manualen.
|
|
Du bygger alt på nytt.
|
|
- **Onboarding.** Ny utvikler leser manualen og forstår hele stacken.
|
|
- **Revisjon.** Manualen er en snapshot av faktisk tilstand —
|
|
ikke intensjoner, ikke planer, men hva som kjører nå.
|
|
- **AI-kontekst.** Claude leser manualen og har komplett bilde
|
|
uten å traversere 90+ filer.
|
|
|
|
## Hva den inneholder
|
|
|
|
### 1. Infrastruktur
|
|
- Server-spec (OS, IP, DNS-oppføringer, domener)
|
|
- Installerte pakker (Rust, Node.js, Docker, Caddy)
|
|
- Brukere og rettigheter
|
|
- Katalogsstruktur (`/srv/synops/`, `/home/vegard/synops/`)
|
|
|
|
### 2. Database
|
|
- PG-skjema (generert fra faktisk database, ikke docs)
|
|
- Alle tabeller, kolonner, typer, indekser, constraints
|
|
- Kjente node_kinds og edge_types (fra faktisk data)
|
|
- Seed-data (systemkritiske noder: Synops-rot, agent-node,
|
|
arbeidstavle, onboarding)
|
|
- Triggers (LISTEN/NOTIFY)
|
|
|
|
### 3. Tjenester
|
|
For hver tjeneste:
|
|
- Hva den gjør
|
|
- Hvordan den startes (systemd unit / Docker Compose)
|
|
- Konfigurasjon (env-variabler, config-filer)
|
|
- Porter og kommunikasjon
|
|
- Avhengigheter
|
|
- Healthcheck
|
|
|
|
Tjenester: Caddy, vaktmesteren, SvelteKit, PostgreSQL,
|
|
Authentik, LiteLLM, faster-whisper, LiveKit.
|
|
|
|
### 4. CLI-verktøy
|
|
For hvert `synops-*`-verktøy (hentet fra cli_tool-noder i PG):
|
|
- Navn og beskrivelse
|
|
- Usage (--help output)
|
|
- Input/output
|
|
- Avhengigheter
|
|
- Build-instruksjoner (`cargo build --release`)
|
|
|
|
### 5. Caddy-konfigurasjon
|
|
- Komplett Caddyfile (fra faktisk fil, ikke docs)
|
|
- Domene → tjeneste-mapping
|
|
- TLS-oppsett
|
|
|
|
### 6. Applikasjonslogikk
|
|
- Alle node_kinds med beskrivelse og metadata-skjema
|
|
- Alle edge_types med semantikk og metadata
|
|
- Traits-katalog med konfigurasjon per trait
|
|
- Kanban-kolonner for arbeidstavlen
|
|
- Agent-konfigurasjon (node-ID, permissions, rate limits)
|
|
|
|
### 7. Konvensjoner
|
|
- @bot-konvensjonen (chat-interaksjon, work item-fangst)
|
|
- n:-referanser (nodelinking, tilgangsprompt)
|
|
- Privacy-signalering (🔒/👁)
|
|
- Responskvalitet (intelligens/innsats-nivåer, ↑-knapp)
|
|
- Generisk dispatch (synops-{job_type} --payload-json)
|
|
|
|
### 8. Arkitekturprinsipper
|
|
Retningene som har formet systemet — ikke bare hva det gjør,
|
|
men hvorfor det er bygget slik:
|
|
|
|
- **Alt er noder og edges.** Ingen separate tabeller. Visninger
|
|
er spørringer mot grafen.
|
|
- **Unix-filosofi.** Vaktmesteren orkestrerer, CLI-verktøy gjør
|
|
jobben. Én ting, gjort godt. Delt verktøykasse.
|
|
- **Selvdokumenterende system.** Systemet dokumenterer seg selv
|
|
som noder i seg selv. Docs er ikke filer — de er graf-data.
|
|
- **Universelle primitiver.** Tre primitiver (input, mottak,
|
|
kommunikasjon). Alt annet er visninger og edges.
|
|
- **Privat er default.** Input uten edges er privat. Sikkerhet
|
|
by design, ikke konfigurasjon.
|
|
- **Noder er sentrum.** Brukere, team, innhold — alt er noder.
|
|
Tilgang via materialisert tilgangsmatrise fra edges.
|
|
- **Vaktmesteren er tynn.** Auth, HTTP-ruting, STDB-synk.
|
|
All logikk i CLI-verktøy og synops-common.
|
|
- **Generisk dispatch.** `synops-{job_type} --payload-json`.
|
|
Nytt verktøy = binary i PATH. Ingen rekompilering.
|
|
- **@bot er generisk.** Ruterbar, modell-agnostisk. Brukeren
|
|
snakker med "boten", ikke med en spesifikk AI.
|
|
- **Responskvalitet er synlig.** Intelligens og innsats vises.
|
|
Én ↑-knapp for "gi bedre svar".
|
|
|
|
Genereres fra `docs/retninger/`-noder i PG.
|
|
|
|
### 9. Gjenoppbyggingssteg
|
|
Nummerert sekvens fra ren server til kjørende system:
|
|
|
|
```
|
|
1. Provisjoner server (Ubuntu, brukere, SSH)
|
|
2. Installer pakker (Rust, Node.js, Docker, Caddy)
|
|
3. Konfigurer DNS (domener → IP)
|
|
4. Start Docker-tjenester (PG, Authentik, LiteLLM, Whisper, LiveKit)
|
|
5. Kjør PG-migrasjoner (skjema + seed)
|
|
6. Konfigurer Authentik (OIDC-provider, redirect URIs)
|
|
7. Bygg og deploy vaktmesteren (cargo build, systemd)
|
|
8. Bygg og deploy SvelteKit (npm build, systemd)
|
|
9. Bygg CLI-verktøy (cargo build per tool)
|
|
10. Konfigurer Caddy (Caddyfile, reload)
|
|
11. Verifiser (healthchecks, test-requests)
|
|
12. Seed systemdata (Synops-rot, arbeidstavle, agent-node)
|
|
```
|
|
|
|
## Generering
|
|
|
|
```bash
|
|
synops-manual --format md > manual.md # Markdown
|
|
synops-manual --format html > manual.html # Standalone HTML
|
|
synops-manual --format json # Maskinlesbar
|
|
```
|
|
|
|
### Datakilder
|
|
|
|
| Seksjon | Kilde |
|
|
|---------|-------|
|
|
| Infrastruktur | `uname`, `dpkg`, DNS-oppslag, filsystem |
|
|
| Database | `pg_dump --schema-only`, faktiske spørringer |
|
|
| Tjenester | systemd-units, docker-compose.yml, .env |
|
|
| CLI-verktøy | cli_tool-noder i PG + `--help` per binary |
|
|
| Caddy | `/srv/synops/config/caddy/Caddyfile` |
|
|
| Applikasjonslogikk | PG-spørringer (node_kinds, edge_types, traits) |
|
|
| Konvensjoner | docs/-filer (disse er stabile referanser) |
|
|
|
|
### Hva den IKKE inkluderer
|
|
|
|
- Secrets (API-nøkler, passord, tokens) — erstattet med `<REDACTED>`
|
|
- Brukerdata (innhold, meldinger, mediefiler)
|
|
- Git-historikk
|
|
- CAS-innhold (binærfiler)
|
|
|
|
## Automatisk generering
|
|
|
|
Manualen regenereres:
|
|
- **Daglig** via cron (fanget av `synops-snapshot` eller separat)
|
|
- **Ved deploy** (post-hook i systemd)
|
|
- **Manuelt** ved behov
|
|
|
|
Lagres som:
|
|
- `docs/MANUAL.md` i repo (committes)
|
|
- Synops-noden i PG (som innhold på en `content`-node)
|
|
|
|
## Diff-modus
|
|
|
|
```bash
|
|
synops-manual --diff
|
|
```
|
|
|
|
Sammenligner nåværende tilstand med sist genererte manual.
|
|
Viser hva som har endret seg — nye tjenester, endrede porter,
|
|
nye CLI-verktøy, skjemaendringer. Nyttig for review.
|
|
|
|
## Bygger på
|
|
- `docs/concepts/selvdokumenterende_system.md` — docs som noder
|
|
- `docs/concepts/arbeidstavlen.md` — synops-snapshot
|
|
- `docs/setup/produksjon.md` — eksisterende oppsettdok (input)
|
|
- `docs/retninger/unix_filosofi.md` — CLI-verktøy konvensjoner
|