183 lines
6.0 KiB
Markdown
183 lines
6.0 KiB
Markdown
# VAUCO OS — ARCHITECTURE.md
|
|
# Eier: PLAN-Claude-Architect
|
|
# Sist oppdatert: 2026-06-29 CEST
|
|
# Godkjent av: Chris Christiansen
|
|
|
|
---
|
|
|
|
## Hensikt
|
|
Single source of truth for systemarkitektur, komponent-diagram og design-kontrakter.
|
|
Ingen andre tråder skriver denne filen. Andre tråder kan foreslå patcher via PR.
|
|
|
|
---
|
|
|
|
## Komponent-diagram (ASCII)
|
|
|
|
```
|
|
[Chris / Operatør]
|
|
|
|
|
-----+------+----------+----------+
|
|
| | | |
|
|
OPS EXEC PLAN AUDIT
|
|
Perplexity Gemini Claude Nemotron
|
|
Computer 2.5 Pro Sonnet/ (NMT)
|
|
Opus
|
|
| | | |
|
|
+-----+-----+----------+----------+
|
|
|
|
|
[GitHub]
|
|
OSVauco (main)
|
|
vauco-bootstrap (main)
|
|
|
|
|
[GCP / Cloud Run]
|
|
project: propane-will-491900-m5
|
|
region: us-central1
|
|
|
|
|
[OPAX-MCP — opax.vauco.no]
|
|
service: opax-mcp-core
|
|
protocol: OPAX Protocol
|
|
|
|
|
[Klient-OS]
|
|
<klient>-oss.vauco.no (stage)
|
|
<klient>-os.vauco.no (prod)
|
|
```
|
|
|
|
---
|
|
|
|
## VM-infrastruktur (GCP Compute Engine)
|
|
|
|
| VM | Formål | Specs | Modeller |
|
|
|----|--------|-------|----------|
|
|
| `osvauco-dev-vm` | Utvikling, OSV-pipeline (lokal Ollama), MCP-testing | **16 GB RAM**, CPU-only, `us-central1-b` | gemma3:4b (3.3 GB), qwen2.5:7b (4.7 GB), nomic-embed-text, llama3.2 |
|
|
| `emma-gpu-vm` | Tung ML, Emma co-pilot (Gemma 4 27B) | GPU, høy RAM | Gemma 4 27B (int4) — kun ved eksplisitt eskalering |
|
|
|
|
### OSV-pipeline (agents/osv/pipeline.py)
|
|
|
|
Lokal tre-lags Ollama-pipeline på `osvauco-dev-vm` for å minimere API-kostnader:
|
|
|
|
```
|
|
Lag 1 — gemma3:4b (front) → forstår intent, strukturerer oppgave
|
|
Lag 2 — qwen2.5:7b (analyse) → dyptgående analyse, kode, planlegging
|
|
Lag 3 — gemma3:4b (output) → formaterer og leverer svar til bruker
|
|
```
|
|
|
|
**Eskaleringspolitikk (Emma):**
|
|
- `emma` trigger: kun hvis Chris eksplisitt skriver "emma" i meldingen
|
|
- `ask_emma`: pipeline spør Chris hvis konfidans < 0.4
|
|
- Aldri automatisk eskalering
|
|
- Emma kjører på `emma-gpu-vm:11434` — kostnad påløper ved oppstart
|
|
|
|
**Viktig — RAM-krav:**
|
|
- `osvauco-dev-vm` MÅ ha ≥16 GB RAM for å kjøre gemma3:4b + qwen2.5:7b samtidig
|
|
- 8 GB er ikke tilstrekkelig — modellene timeout-er under lasting
|
|
- Øk VM til 16 GB i GCP Console ved behov
|
|
|
|
---
|
|
|
|
## MCP Identity
|
|
|
|
| Parameter | Verdi |
|
|
|----------------|------------------------------------|
|
|
| MCP_NAME | OPAX-MCP |
|
|
| MCP_PROTOCOL | OPAX Protocol |
|
|
| MCP_SERVICE | opax-mcp-core |
|
|
| Cloud Run | us-central1 |
|
|
| HUB_URL | https://opax.vauco.no (Phase 2) |
|
|
|
|
---
|
|
|
|
## Domenekonvensjon — LOCKED
|
|
|
|
| Subdomain | Type | Formål |
|
|
|-------------------------|----------|---------------------------------------------------|
|
|
| `opax.vauco.no` | Hub/MCP | OPAX-MCP operator hub — kun Vauco internt |
|
|
| `<klient>-os.vauco.no` | Prod OS | Kundens live produksjonssystem |
|
|
| `<klient>-oss.vauco.no` | Stage OS | Kundens staging/demo-system (pre-go-live) |
|
|
|
|
> `-os` = produksjon. `-oss` = staging. Aldri omvendt.
|
|
|
|
### Auth-strategi
|
|
- **Nå:** Google OAuth på alle miljøer
|
|
- **Senere:** BankID på `-os`-domener for kliniske kunder (Medioteq først)
|
|
|
|
### Kjente / planlagte domener
|
|
|
|
| Domene | Status | Cloud Run-tjeneste |
|
|
|-------------------------|---------------|-----------------------|
|
|
| `opax.vauco.no` | DNS pending | `opax-mcp-core` ✅ |
|
|
| `medioteq-oss.vauco.no` | Planlagt | `medioteq-oss-core` |
|
|
| `medioteq-os.vauco.no` | Planlagt | `medioteq-os-core` |
|
|
|
|
---
|
|
|
|
## Tråd-kontrakter
|
|
|
|
| Tråd | Modell | Eid fil | Konnektor |
|
|
|---|---|---|---|
|
|
| OPS-Computer-Hub | Perplexity Computer | AGENT_RULEBOOK.md, LEARNINGS.md, CHANGELOG.md | GitHub web, search |
|
|
| EXEC-Gemini-Workstation | Gemini 2.5 Pro | SYSTEM_STATE_AGENT_BOOT.md, TODO.md | shell, gcloud, git |
|
|
| PLAN-Claude-Architect | Claude Sonnet/Opus | ARCHITECTURE.md (denne), ROADMAP.md | GitHub UI/API |
|
|
| AUDIT-NMT-Critic | Nemotron | RISKREGISTER.md, PLANBOARD.md | read-only alle filer |
|
|
|
|
Regel: En fil — én eier. Andre tråder foreslår via PR, eier merger.
|
|
|
|
---
|
|
|
|
## Dataflyt
|
|
|
|
```
|
|
OPS --[MD-patch PR]--> PLAN merger
|
|
EXEC --[SYSTEM_STATE]--> alle leser
|
|
PLAN --[arch-spec PR]--> EXEC implementerer
|
|
AUDIT--[PLANBOARD]--> Chris prioriterer
|
|
|
|
Filer flyter via: GitHub commits på OSVauco/main
|
|
Aldri: direkte tråd-til-tråd
|
|
```
|
|
|
|
---
|
|
|
|
## Klientmodell — Prosjektisolasjon
|
|
|
|
**Prinsipp:** Hver klient med sensitiv/medisinsk data får eget GCP-prosjekt.
|
|
|
|
| Lag | GCP-prosjekt | Rolle |
|
|
|-----|-------------|-------|
|
|
| OPAX/OSVauco | `propane-will-491900-m5` | Management plane — deploy, monitor, orchestrate |
|
|
| Medioteq klinisk | `<medioteq-project-id>` | Data plane — kliniske data forblir her |
|
|
|
|
- OPAX mottar **aldri** rå pasientdata
|
|
- Data-residency: `europe-north1` for norske helsedata
|
|
- Alle agentkall logges til BigQuery i klientprosjektet (input/output hash, ikke råinnhold)
|
|
|
|
---
|
|
|
|
## Avhengigheter
|
|
|
|
- `OSVauco/main` er canonical branch for dette prosjektet
|
|
- Cloud Run avhenger av `vauco-gemini-tui-bridge` og OPAX-MCP-tjenesten
|
|
- Bridge avhenger av `bridge/`-kode + GCP service account `vauco-dev`
|
|
- Token economy avhenger av `scripts/token_economy.py` (planlagt)
|
|
- Pre-commit hook v2 avhenger av `.githooks/pre-commit` (planlagt)
|
|
- OSV-pipeline avhenger av Ollama på `osvauco-dev-vm` med ≥16 GB RAM
|
|
|
|
---
|
|
|
|
## Åpne spørsmål (max 3)
|
|
|
|
1. **Langsiktig repo-struktur?**
|
|
- A: Behold OSVauco + tjeneste-repoer (nåværende)
|
|
- B: Slå sammen til monorepo
|
|
- C: Splitt ytterligere per tjeneste
|
|
|
|
2. **Cloud Run min-instances=0 eller 1?**
|
|
- A: 0 — kutter idle-kostnad (anbefalt H0)
|
|
- B: 1 — ingen cold start latency
|
|
|
|
3. **IAM: vauco-dev service account scope?**
|
|
- A: Minimal — kun Vertex AI + Firestore
|
|
- B: Per-skill separate accounts
|
|
|
|
---
|
|
EOF v1.2 — 2026-06-29 — OPS (osvauco-dev-vm + OSV-pipeline + Emma-eskaleringspolitikk lagt til)
|