# 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)