chris/OSVauco
1
0
Fork 0
Code Issues 1 Pull Requests Actions 2 Packages Projects Releases Wiki Activity
1f4df47083
OSVauco/docs/ARCHITECTURE.md

6.0 KiB
Raw Blame History

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)