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

14 KiB
Raw Blame History

VAUCO OS — MASTERPLAN

Eier: Chris Christiansen · Vauco AS · Org.nr 935 989 779 Sist oppdatert: 2026-06-12 Status: 🟢 AUTORITATIV — én kilde til sannhet for hele Vauco-økosystemet

Regel #1: Denne filen er sannheten. Hvis en annen fil sier noe annet — denne vinner. Regel #2: Endringer her krever eksplisitt PLAN APPROVED fra Chris. Regel #3: Roadmap → seksjon 7. Sesjonsstatus → docs/HANDOFF.md. Ingen andre handoff-filer.

Lessons Learned

  • Cloud Build smoke-tests require: hardcoded canonical BASE_URL, bare identity token (no --audiences), and explicit run.invoker IAM binding for the Cloud Build service account on every service.
  • 2026-06-10 — Absolutte filstier i Python: Bruk alltid Path(__file__).parent / "..." for å referere til statiske filer og konfigurasjon i FastAPI/Cloud Run. Aldri relativ sti som "static/file.html" — dette bryter når WORKDIR avviker fra repo-rot (f.eks. i Docker). Regelen gjelder alle fremtidige tjenester og klientleveranser.
  • 2026-06-10 — Dockerfile COPY static/: static/-mappen må eksplisitt kopieres inn i Docker-imaget via COPY static/ ./static/. Den kopieres ikke automatisk selv om build-konteksten er repo-roten.
  • 2026-06-10 — app.py mangler GET /: FastAPI returnerer {"detail":"Not Found"} for alle ruter som ikke er definert. Sørg alltid for at rot-ruten er eksplisitt definert.
  • 2026-06-12 — Mappestruktur må verifiseres mot repo: MASTERPLAN-dokumentasjon av mappestruktur må alltid verifiseres via GitHub API før bygging. Antakelser om struktur er ikke nok.

1. Plattformhierarki — sannheten i én modell

Vauco AS  (selskap, eier alle merkevarer)
│
├── vauco.no  (APEX — bedriftens salgs- og portalside; ansiktet utad)
│
└── VAUCO OS  (plattform)
      └── OPAX  (engine — Cloud Run, RAG, agentic arkitektur, IAP)
            ├── Modul #1 · CostGuard       (live på costguard.oss.vauco.no)
            ├── Modul #2 · Threadstone     (landingsside live, app i bygg)
            └── Modul #3 · [navngis senere]

Separat merkevare (parkert):
└── Proof of Curiosity
Nivå Hva Hvem ser det
vauco.no (apex) Bedriftens salgsportal Alle
Vauco OS Plattformen Chris bygger Internt
OPAX Engine som driver modulene Internt + utviklere
Modul Det kundene kjøper Kunder

Ikke selg Vauco OS. Ikke selg OPAX. De er interne verktøy.

2. Registrerte domener — fasit

Aktive subdomener:

Domene/subdomen Teknologi Status
vauco.no (apex) GCS + LB + CDN ✅ LIVE 2026-06-05
opax.vauco.no LB + IAP → Cloud Run ✅ Live (IP 34.98.77.173)
oss.vauco.no Staging ✅ Aktiv
costguard.oss.vauco.no Cloud Run via IAP ✅ Live
threadstone.vauco.no GitHub Pages ✅ Live
app.threadstone.vauco.no GitHub Pages ⚠️ CNAME satt, side mangler
os.vauco.no Prod-miljø 🔮 Fase C

Email-infra: MX + SPF/DKIM/DMARC ✅ Live 2026-06-10

3. Repo-struktur — fasit

Aktive repos (5)

Repo Formål Synlighet
OSVauco Mono-repo: OPAX-engine, infra, Terraform, all dokumentasjon Privat
vauco-bootstrap Terraform-modul for kunde-provisjonering Privat
vauco-site vauco.no salgsportal Public
threadstone-landing threadstone.vauco.no landingsside Public
vauco-saas.github.io Threadstone-app frontend Public

Regel: Nytt repo krever eksplisitt REPO APPROVED fra Chris.

4. OSVauco — FAKTISK mappestruktur (verifisert 2026-06-12)

VIKTIG: Denne seksjonen er verifisert mot GitHub API. Ikke anta struktur — alltid verifiser.

OSVauco/                          (root)
├── main.py          (26 KB)    ⭐ HOVUDAPPLIKASJON — FastAPI app + alle ruter
├── AGENTS.md
├── CLAUDE.md                   ← Kontekstfil for Claude-agenter
├── README.md
├── CNAME
├── cloudbuild.yaml             ← CI/CD trigger
├── cloudbuild.base.yaml
├── requirements.txt
├── .env.example / .env.prefilled
├── dev-startup.sh / opax.sh
│
├── agents/                     ← Agent-logikk (ikke hovudapp)
├── architecture/               ← Arkitekturdokumenter
├── auth/                       ← Auth-logikk
├── data/
├── dialogflow/                 ← Dialogflow-integrasjon
├── docs/                       ← All dokumentasjon
│   ├── MASTERPLAN.md
│   ├── ROADMAP.md
│   ├── HANDOFF.md
│   ├── AGENT_RULEBOOK.md
│   ├── UNIVERSAL_BOOT_PROMPT.md
│   ├── LEARNINGS.md
│   ├── ARCHITECTURE.md
│   ├── AGENTIC_CONTRACT_MCP_PROVISIONING.md
│   ├── DNS-OG-INFRASTRUKTUR.md
│   ├── SECRETS-SETUP.md
│   ├── LEARNINGS_CICD_2026-06-10.md
│   ├── GCP_Best_Practices.md
│   └── gemma/
│       └── world.md   ❌ MANGLER — blokkerer ML-3a/Emma-boot
├── infrastructure/
├── master_hub/                 ← Eksisterer — formål ikke klarlagt
├── ml/
├── opax-mcp/                   ← MCP-server (ikke agents/mcp_server/)
├── protocols/
├── scripts/
└── static/
    ├── opax.html               ✅ CG4d prisingskalkulator
    ├── costguard-dashboard.html ✅ CG6 klient-dashboard
    ├── jason.html
    ├── billing-dashboard.html
    ├── costguard.html
    ├── command-hub.html
    └── admin.html

Kritiske korreksjoner fra tidligere feil dokumentasjon:

  • main.py (rot) er hovudapplikasjonen — IKKE agents/core-logic/app.py
  • MCP-server ligger i opax-mcp/ — IKKE agents/mcp_server/
  • master_hub/ og dialogflow/ eksisterer — formål må kartlegges
  • Nye ruter/endepunkter legges i main.py — ikke i agents/

4b. vauco.no — salgsportal

Versjon Inneholder Trigger
V1 (MVP) ✅ Hero + modul-grid + om-oss + kontakt LIVE 2026-06-05
V2 Sales-CTA + ROI-kalkulator Etter første betalende kunde
V3 Blogg, kundereferanser Når 3+ kunder

5. Dokumenthierarki

Fil Rolle
docs/MASTERPLAN.md Autoritativ sannhet
docs/ROADMAP.md Faser og status
docs/HANDOFF.md Sesjonsstatus — overskrives hver sesjon
docs/AGENT_RULEBOOK.md Locked agent-regler
docs/UNIVERSAL_BOOT_PROMPT.md Boot-protokoll v1.4
CLAUDE.md Kontekst for Claude-agenter (rot)
docs/gemma/world.md Emma sin kontekstpakke ❌ mangler

6. AI-modell — tofase-strategi

Fase 1 — Nå

Parameter Verdi
Intern stand-in Perplexity (Sonnet 4.6) via GitHub MCP
Kundemodell (Jason) gemini-2.5-flash via Vertex AI
Region us-central1

Fase 2 — Gemma (trigger: kreditter < 20% eller første kunde)

Parameter Verdi
Emma (intern) gemma-4-12b-it int4 · GCP g2-standard-4 Spot VM
Jason (kunder) gemini-2.5-flash via Vertex — uendret

7. Roadmap — kortversjon

Full status i docs/ROADMAP.md.

🔴 NOW

  • CG4d — Prisingskalkulator i static/opax.html ✅ 2026-06-12
  • CG5a — Delivery layer: POST /notify/webhook ✅ live (commit 4a1e23e, Sonar)
  • CG5b — E-postvarsler: POST /notify/email via SendGrid ✅ live
  • CG6 — Klient-dashboard static/costguard-dashboard.html ✅ 2026-06-12
  • len(agents)-bugfix i /run/dag 🔴
  • CG5-onboard — Klient-onboarding flow 🔴
  • CG5c — SMS-varsler: POST /notify/sms via Twilio [Guard+]

🟠 NEXT

  • CI1 — opax-mcp/ full CI/CD-kanal
  • ML-3a — GPU-VM for Emma + docs/gemma/world.md opprettes
  • C4 — Medioteq partnerstrategimøte

8. Agent-identitet

Identitet E-post Modell Status
Eier chris.christiansen@vauco.no — ✅ Aktiv
Jason Vauger jason.vauger@vauco.no gemini-2.5-flash ✅ Live
Emma Vauger emma.vauger@vauco.no gemma-4-12b-it 🔮 ML-3a

Forbudte kontoer: tinius.vauger, ccv — aldri gi tilganger.

9. Cloud Run — live endepunkter

Service: osvauco-agent · us-central1 · propane-will-491900-m5 Public URL: https://opax.vauco.no

Endepunkt Fil Status
GET / main.py ✅ Serverer opax.html
GET /health main.py ✅
POST /run main.py ✅
GET /static/jason.html main.py ✅
GET /billing/tokens/by-module main.py ✅
GET /billing/tokens/estimate main.py ✅
GET /billing/summary main.py ✅
GET /billing/anomalies main.py ✅
GET /billing/history main.py ✅
GET /billing/budget main.py ✅
POST /billing/budget main.py ✅
POST /notify/webhook main.py ✅ CG5a live
POST /notify/email main.py ✅ CG5b live
POST /notify/sms main.py 🔴 CG5c
GET /notify/channels main.py 🔴 OQ-29

10. Go-to-market

CostGuard — prismodell v2 (godkjent 2026-06-12)

Prinsipp: Push-first — Jason finner kunden, ikke omvendt. Pitch: "Du trenger ikke lære et nytt verktøy. Jason finner deg."

Tier GCP-spend/mnd Pris Kjerneløfte
Starter $0–$3k $499/mnd Synlighet
Guard $3k–$15k $999/mnd Kontroll
Shield $15k–$50k $1.999/mnd Automatisering
Enterprise >$50k $3.500+/mnd Platform

Delivery layer:

GCP-event → Jason → Delivery layer → Webhook (CG5a) / E-post (CG5b) / SMS (CG5c)

Markedsposisjon:

Konkurrent Pris CostGuard vinner på
Kubecost Business $199/mnd GCP-native + Jason AI
Apptio Cloudability $1.930/mnd Enklere, push-first
CloudHealth $5.400+/mnd Pris + SMB-fokus

Medioteq — Joint Venture

Partnersamarbeid, ikke SaaS-kunde. C4 = partnerstrategimøte.

11. Kjente hull

ID Problem Prioritet
OQ-15 BQ billing_export tabell Medium
OQ-17 github-token secret mangler Medium
OQ-18 VM alltid-på kostnad Høy
OQ-21 app.threadstone.vauco.no CNAME uten side Lav
OQ-26 docs/gemma/world.md mangler Høy (ML-3a blokkert)
OQ-27 master_hub/ formål ikke dokumentert Medium
OQ-28 dialogflow/ formål ikke dokumentert Medium
OQ-29 GET /notify/channels mangler i main.py — CG6 faller tilbake på defaults Lav

12. OPAX — status

Ferdig:

  • ✅ opax.html LIVE via GET / (main.py)
  • ✅ Jason-chat LIVE
  • ✅ Billing dashboard + Chart.js donut (CG4b)
  • ✅ Token Intelligence endepunkter
  • ✅ CI5+CI6 — opax-mcp live
  • ✅ CG4d — Prisingskalkulator i opax.html
  • ✅ CG5a — POST /notify/webhook live
  • ✅ CG5b — POST /notify/email live
  • ✅ CG6 — Klient-dashboard costguard-dashboard.html

Gjenstår: len(agents)-bugfix i /run/dag · CG5-onboard · CG5c · CI1 · ML-3a

OSVauco | propane-will-491900-m5 | us-central1 | Autoritativ fra 2026-05-31 | Oppdatert 2026-06-12

13. Telefoni & AI-agent Plan — Phase E tillegg

Konsept: Twilio som kommunikasjonsryggrad

Et Twilio-nummer er grunnmuren for SMS, tale og AI-agent telefoni. Alt bygger på samme konto og nummer.

Lag 1 — Grunnmur (gjøres NÅ, Phase D)

Allerede planlagt:

  • Twilio-konto opprettet
  • TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_FROM_NUMBER lagret i Secret Manager
  • send_sms fungerer via opax-mcp

Lag 2 — Inngående AI-telefonsvarer (Phase E, Uke 3-4)

Konsept

Kunder/kontakter ringer Twilio-nummeret. Emma-agenten tar samtalen, transkriberer og svarer med tale.

Teknisk stack

  • Twilio Programmable Voice + Conversation Relay (WebSocket)
  • Ollama (emma modell) på osvauco-dev-vm som LLM
  • Whisper eller Twilio Speech Recognition for STT
  • Twilio TTS (eller Google TTS) for tale tilbake

Flyt

Innringer → Twilio → WebSocket → opax-mcp → Ollama (Emma) Emma svarer → TTS → Twilio → Innringer

Hva Emma kan gjøre under samtalen

  • Svare på spørsmål om OSVauco-tjenester
  • Slå opp kundedata i backend
  • Booke møter og sende SMS-bekreftelse
  • Si "ett øyeblikk" og hente live data via MCP-tools
  • Eskalere til Chris eller Jason med full samtale-kontekst

Implementasjon

  1. Legg til /voice webhook-endepunkt i opax-mcp
  2. Konfigurer Twilio Voice URL til opax-mcp Cloud Run
  3. Bygg ConversationRelay WebSocket-handler
  4. Koble til Ollama via eksisterende MCP-infrastruktur
  5. Definer Emma sin persona og instrukser for telefon
  6. Test med internt nummer først

Lag 3 — Utgående AI-anrop (Phase E, Uke 5-6)

Konsept

Emma ringer proaktivt — f.eks. kostnadsvarsler, møtepåminnelser, oppfølging av kunder.

Flyt

Trigger (kostnadsspike / planlagt tid) → Emma initierer anrop via Twilio Outbound API → Samme ConversationRelay-stack som inngående

Bruksområder

  • "Hei, jeg ringer fra Vauco — dere nærmer dere budsjettgrensen på GCP denne måneden"
  • Møtepåminnelse dagen før
  • Oppfølging etter demo

Lag 4 — Multikanal-orkestrering (Phase F)

Konsept

Emma bestemmer selv hvilken kanal som passer:

  • Lav prioritet → SMS
  • Medium → E-post (Gmail API, allerede oppe)
  • Høy prioritet → Telefonanrop
  • Intern → Google Chat webhook

Implementasjon

Legg til kanalvalg-logikk i Emma sin system-prompt: "Velg kanal basert på hastegrad og brukerpreferanse"

Personas per kanal

Kanal Avsender Persona
SMS +47-Twilio-nummer Nøytral, kort
E-post jason.vauger@vauco.no Profesjonell
Telefon inngående Emma Vennlig, hjelpsom
Telefon utgående Emma Proaktiv, konsis

Kostnadsestimat Twilio

Tjeneste Kostnad
Telefonnummer ~$1/mnd
SMS utgående (NO) ~$0.07/SMS
Voice inngående ~$0.0085/min
Voice utgående ~$0.014/min
Trial credits $15 gratis ved oppstart