OSVauco/docs/ARCHITECTURE.md

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

---

## Dual-layer deploymodell: B over A

# Vauco Architecture Manifest

## Core Thesis

Vauco should use a dual-layer deployment model in which **Model B governs Model A**. The internal OPAX-MCP control plane should own policy, approvals, orchestration, and capability boundaries, while the simpler Cloud Build trigger pattern remains the standardized execution path for services that benefit from a repeatable and low-friction deployment flow.

This approach fits the documented profile model, where operator capabilities are broad and privileged while external, family, customer, or blueprint-driven profiles receive narrower and safer capabilities. It also matches the existing direction that OPAX-MCP is the external gateway and governance surface, while Gitea remains the source of truth for code.

## Layer Model

### Layer 1: Gitea as code truth

Gitea is the intended primary source of truth for code, and the repository flow has already been shifted toward Gitea-first operation rather than GitHub-first day-to-day work. This means repository state, branches, commits, and promotion events should originate from Gitea even when downstream deployment mechanisms differ by service type.

### Layer 2: Model A as standard execution plane

Model A is the standardized deploy mechanism: a declarative Cloud Build pipeline builds the image, pushes it to Artifact Registry, renders a temporary service manifest from opax-mcp.yaml, and applies it with gcloud run services replace. This makes Model A suitable as the simple operational path for services that benefit from repeatable, low-drama deployment behavior.

Model A should therefore be treated as the default execution substrate for client-facing or repeatable services, especially where simplicity, supportability, and low operator friction matter more than deep custom orchestration. It is an execution mechanism, not the long-term brain of the platform.

### Layer 3: Model B as internal control organ

Model B is the internal OPAX-MCP-owned control organ. Its documented architecture places webhook verification, approval handling, SMS-based HITL, and deploy orchestration inside OPAX-MCP itself, culminating in a controlled gcloud builds submit using the existing declarative pipeline file.

In this architecture, Model B does not need to replace Model A everywhere. Instead, Model B should govern when Model A is created, updated, permitted, or bypassed, allowing Vauco to keep a proprietary control plane without forcing every service into the same high-complexity execution path.

## Design Principle

The key principle is **complexity in the core, simplicity at the edge**. OPAX-MCP should centralize policy, operator powers, capability boundaries, and architectural governance, while simpler deployment channels remain available for services that do not need bespoke orchestration.

This is operationally healthier than making every deployment path equally advanced. A system where every service must go through the most complex path increases cognitive load and failure analysis burden, while a system with no internal control organ increases fragmentation across triggers, consoles, and undocumented workflows.

## Why This Fits Vauco

This dual model supports the existing profile strategy. The documented access model already distinguishes operator access from family, blueprint, and customer access, which implies a future where capabilities are governed centrally rather than exposed raw to every actor.

It also supports the documented learning-loop strategy: quality should come from verified events, clear diffs, explicit blockers, and curated operational truth instead of uncontrolled growth in tools or context. A layered model makes it easier to preserve that discipline because the control plane can observe, gate, and record the simpler execution plane rather than becoming identical to it.

## Trade-offs
| Topic | Model A alone | Model B alone | Hybrid: B governs A |
|---|---|---|---|
| Speed to restore deploy flow | High | Low to medium | High for standard paths, medium for advanced paths |
| Proprietary control | Lower | Higher | High where it matters, moderate where standardization is enough |
| Cognitive load | Lower initially | Higher initially | Lower at edge, concentrated in operator core |
| Platform value over time | Moderate | High | High, with incremental rollout |
| Suitability for profiles/capabilities | Limited | Strong | Strong |

## Governance Rules
To avoid dual-truth drift, the following architectural rules should hold:

- Gitea is the source of truth for code and repository events.

- opax-mcp.yaml is the deploy configuration truth for opax-mcp and should not be bypassed by ad-hoc imperative deploys.

- OPAX-MCP is the policy and control truth for operator-level orchestration and future capability governance.

- Model A is a standard execution mechanism used by policy, not an independent architectural authority.

## Recommended Path
The recommended path is to restore and stabilize Model A first as the immediate execution layer, because the declarative pipeline file already exists and is the fastest way to stop manual deployment drift. After that, Model B should be built deliberately as the internal governance and orchestration layer that can manage or supersede Model A where appropriate.

This sequence preserves momentum without giving up the proprietary direction. It creates a platform in which Vauco can scale simple services through standardized execution while reserving deeper operator control for the places where control, policy, and identity matter most.