415 lines
14 KiB
Markdown
415 lines
14 KiB
Markdown
# 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
|
||
- [x] CG4d — Prisingskalkulator i `static/opax.html` ✅ 2026-06-12
|
||
- [x] CG5a — Delivery layer: `POST /notify/webhook` ✅ live (commit 4a1e23e, Sonar)
|
||
- [x] CG5b — E-postvarsler: `POST /notify/email` via SendGrid ✅ live
|
||
- [x] 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 |
|