Spesifiser synops-manual: komplett teknisk instruksjonsmanual fra faktisk tilstand
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) <noreply@anthropic.com>
This commit is contained in:
parent
8e80102f6b
commit
71d9bbf25f
1 changed files with 171 additions and 0 deletions
171
docs/features/systemmanual.md
Normal file
171
docs/features/systemmanual.md
Normal file
|
|
@ -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 `<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
|
||||
Loading…
Add table
Reference in a new issue