From 71d9bbf25fd315fdd945bdd24707c7dafdd6a901 Mon Sep 17 00:00:00 2001 From: vegard Date: Wed, 18 Mar 2026 12:29:22 +0000 Subject: [PATCH] Spesifiser synops-manual: komplett teknisk instruksjonsmanual fra faktisk tilstand MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ny feature-spec for selvgenererende systemmanual: - Genereres fra faktisk tilstand (PG-skjema, systemd, Docker, CLI) - 9 seksjoner: infra, DB, tjenester, CLI, Caddy, app-logikk, konvensjoner, arkitekturprinsipper, gjenoppbyggingssteg - Selvforsynt: gitt ren server + manual = kjørende system - Diff-modus for å se hva som har endret seg - Secrets redacted, brukerdata ekskludert - Daglig regenerering + ved deploy Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/features/systemmanual.md | 171 ++++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 docs/features/systemmanual.md diff --git a/docs/features/systemmanual.md b/docs/features/systemmanual.md new file mode 100644 index 0000000..dc3e69f --- /dev/null +++ b/docs/features/systemmanual.md @@ -0,0 +1,171 @@ +# 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, portvokteren, 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.** Portvokteren 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. +- **Portvokteren 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 portvokteren (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 `` +- 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