openova/docs/PERSONAS-AND-JOURNEYS.md

Personas and Journeys

Status: Authoritative target experience. Updated: 2026-04-27. Implementation: The journeys described use Catalyst surfaces (console / Git / API) that are design-stage. See IMPLEMENTATION-STATUS.md.

How different people use Catalyst. Defer to GLOSSARY.md for terminology.

---

1. Personas

#	Persona	Where they live	Tools they use
P1	OpenOva Engineer	github.com/openova-io	Catalyst codebase, Blueprint repos
P2	sovereign-admin	Catalyst admin UI + Sovereign Gitea	Browser UI, Git, kubectl (debug)
P3	Support Agent (within a Sovereign's operations team)	Catalyst admin UI in support mode	Browser UI
P4	org-admin	Org-scoped Catalyst console	Browser UI, occasional Git
P5	SME End User (e.g. Ahmed, pharmacy owner on Omantel)	Marketplace + the App they installed	Browser only
P6	SME Power User (e.g. Ahmed's tech-savvy nephew)	Console with Developer mode toggled on	Browser, occasionally Git
P7	Corporate DevOps / SRE (e.g. Layla at Bank Dhofar)	Git + console in advanced view	Browser, Git, kubectl-on-own-vcluster, IDE
P8	Corporate App Developer (e.g. Omar at Bank Dhofar)	Console + Git for own service repos	Browser, Git, IDE
P9	Security/Compliance Officer (e.g. Khalid, CISO)	Audit dashboards + EnvironmentPolicy editor	Browser
P10	Billing Admin	Billing console	Browser

---

2. Surfaces

The three first-class surfaces (full list and rationale in ARCHITECTURE.md §7):

• UI — Catalyst console. Form / Advanced / IaC editor depths.
• Git — direct push or PR to the Application's Gitea repo (one repo per App; branches develop/staging/main map to dev/stg/prod), or to private Blueprint repos (shared-blueprints per-Org or catalog-sovereign Sovereign-wide).
• API — REST + GraphQL, for portal integrations.

Plus one debug-only surface:

• kubectl — inside one's own vcluster. Read-mostly, never used to mutate Catalyst-managed resources.

There is no fourth surface. Terraform, Pulumi, "catalystctl install" are not part of this model.

---

3. Personas × Journeys matrix

Cells show which surface(s) the persona uses for that journey. Bold = primary. Italic = secondary. Empty = not applicable.

	P1	P2	P3	P4	P5	P6	P7	P8	P9	P10
J1 Build & publish Blueprint to public catalog	Git + CI
J2 Provision a Sovereign		UI+Git
J3 Onboard an Organization		UI	UI
J4 Create an Environment		UI		UI	auto on signup	UI	UI		view audit
J5 Install Application from catalog				UI	UI form	UI	UI + Git	UI + Git	view audit	view cost
J6 Configure Application				UI	UI form	UI	UI + Git	UI + Git	view audit
J7 Author private Blueprint		Git+CI				UI + Git	Git + CI	Git + CI	review + sign
J8 Author Crossplane Composition (advanced)	Git + CI	Git+CI					Git + CI		review
J9 Promote between Environments				UI			UI + Git PR	UI + Git PR	UI approve
J10 Observe runtime / debug		UI dashboards	UI dashboards	UI dashboards	App's own UI	UI	UI + kubectl	UI + kubectl	UI audit
J11 Rotate credentials		UI + auto		UI + auto	auto	UI	UI + auto		UI + policy
J12 Audit / compliance review		UI	UI	UI			UI (own changes)	UI (own changes)	UI export to SIEM
J13 Billing & quotas		UI quotas	UI read	UI invoices	UI plan					UI
J14 Off-board / migrate		UI export		UI	UI cancel		UI export		audit	UI final invoice

---

4. Two journey narratives, end-to-end

4.1 SME journey — Ahmed at Muscat Pharmacy (on Omantel)

Cast. Ahmed owns 4 small pharmacies in Muscat. No IT staff. He has a laptop and a credit card.

Day 1 — 14:00
─────────────
1. Ahmed visits omantel.openova.io. Sees the marketplace. No login required.
2. Picks "Pharmacy Starter Bundle" — a composite Blueprint
   (bp-bundle-pharmacy: ERPNext + WooCommerce + Stalwart-mail + Postgres + Redis).
3. Clicks "Get Started" → Omantel-branded signup. Phone OTP via Omantel mobile
   bill verification (federated identity). Account created.
4. Catalyst auto-creates: Organization "muscatpharmacy", Environment
   "muscatpharmacy-prod", vcluster "muscatpharmacy" on hz-fsn-rtz-prod.
   Environment-controller spins up the vcluster in ~60 seconds.
5. Bundle install wizard: 3 simple steps —
   Step 1: subdomain (muscatpharmacy.shop.omantel.com)
   Step 2: business details (form generated from Blueprint configSchema)
   Step 3: payment plan (BHD 49/month)
6. Click Install. Provisioning service creates 5 Application Gitea repos under
   gitea.<location-code>.omantel.openova.io/muscatpharmacy/ (one repo per App:
   erpnext, woocommerce, pharmacy-mail, shared-postgres, shared-redis), each
   with `develop`/`staging`/`main` branches and initial manifests.
   Webhook → projector → Flux in the muscatpharmacy vcluster picks up the
   N new GitRepository sources and reconciles.
7. ~3 minutes later: Ahmed sees green checkmarks on his dashboard.
   Each App card has an "Open" button.
   Click ERPNext → SSO via Omantel federated identity → he's in.
─────────────
Day 1 — 14:08 — Ahmed is selling.

What he never saw: Git, kubectl, vcluster, Flux, Blueprint, YAML, JetStream. His mental model: "I have an Omantel account. I bought a bundle. It works."

4.2 Corporate journey — Layla at Bank Dhofar (running its own Sovereign)

Cast. Layla is an SRE on Bank Dhofar's 12-person Cloud Platform team. They run their own Sovereign on Hetzner. Their internal Organizations are core-banking, digital-channels, analytics, corporate-it. Their default tooling is Git + IDE.

09:00  Coffee. Opens VS Code. Branch: bp-bd-payment-rail
─────────────────────────────────────────────────────────────────────────
       She's authoring a private Blueprint for a payment-rail microservice
       with Postgres + Redis dependencies.

09:15  Pushes to gitea.<location-code>.bankdhofar.local/digital-channels/shared-blueprints/
       bp-bd-payment-rail. CI in Bank Dhofar's GitHub Actions runner pool
       (running inside the Sovereign) builds the image, signs the Blueprint
       with cosign, publishes to the local OCI registry. blueprint-controller
       picks it up — visible as a private card in the digital-channels Org.

10:00  Switches to her Application repo:
       gitea.<location-code>.bankdhofar.local/digital-channels/payment-rail
       Checks out branch `develop` (the dev environment branch).
       Edits values.yaml (config tweak).
       Catalyst console (Plan view) shows the diff: what will change,
       dependency impact, drift, cost delta. Like terraform plan, but
       served by the API on the Git diff.

10:15  Happy. Commits to develop. Webhook → projector → Flux in the
       digital-channels vcluster (watching the develop branch on this
       Application repo) reconciles in 30s. Audit log captures her as
       committer at the App-repo level.

11:00  Need to debug the staging deployment of the same App.
       Browser: console → digital-channels-stg → payment-rail card
       → Logs tab. Then Topology tab to see across regions.
       Or, drops into kubectl scoped to her vcluster:
         $ kubectl --context=hz-fsn-rtz-prod-digital-channels logs -n payment-rail
       Direct kubectl, scoped strictly to her Org's vcluster (vcluster name
       per NAMING §1.5 is the Org name, not the Sovereign name — Layla's Org
       is `digital-channels`). Bank Dhofar's sovereign-admin grants this via
       a JIT elevation flow.

14:00  Promotion stg → uat. From the payment-rail Application card,
       clicks "Promote staging → uat". Catalyst opens a Gitea PR
       within the same payment-rail repo: source branch `staging`,
       target branch (a feature branch tracking uat config). The
       EnvironmentPolicy CR for digital-channels-uat (in
       system/catalyst-config/policies/) requires team-platform approver
       and an RE score ≥ 80%. Reviewer approves via Gitea web UI (or
       via the Catalyst console's PR view — same backend). Auto-merge.
       Flux in the uat-bound vcluster reconciles.

15:00  New Environment needed for a fraud lab. From the console:
       "New Environment in analytics" → fills name "fraud-lab-dev" →
       picks "small" topology (1 region, single bb=rtz). Environment-controller
       creates the vcluster and bootstraps Flux pointing at the develop
       branch of every Application repo in the analytics Org. No new repos
       are created (Application repos exist already, indexed by branch).
       Ready in 60s. Layla now has a new sandbox.

16:00  Business asks for the bank's existing Backstage portal to show
       Catalyst-managed services. Layla integrates: Backstage queries
       Catalyst REST API at https://api.<location-code>.bankdhofar.local/v1/applications,
       authenticated via SPIFFE SVID (workload identity — Backstage runs
       inside the Sovereign and gets a SPIRE-issued SVID). Backstage's
       service catalog now includes Catalyst Applications alongside other
       systems. No code change in Catalyst — the API was already there.

What Layla DOES use: UI (for promotion approvals, observability, EnvironmentPolicy editing), Git (for Blueprint authoring in shared-blueprints and per-Application config in each App's repo with develop/staging/main branches), kubectl (for debugging her own vcluster), and the API (for integrating Backstage). She never writes Crossplane code unless she's contributing a new Composition upstream as a Blueprint — and even then it's via a Gitea PR.

What Layla doesn't use: Terraform, Pulumi, a "catalystctl" CLI, or any other tool that bypasses Git.

---

5. Application card (the user's primary handle)

The card is the user's view of an Application in their Environment. Anatomy below; full UX in the console docs.

┌────────────────────────────────────────────────────────────────┐
│  🌐  marketing-site                                       ⋮   │  ← name + menu
│      bp-wordpress @ 1.3.0                                      │  ← Blueprint + version
├────────────────────────────────────────────────────────────────┤
│  ●  Running         🔗 acme.com  ↗                             │  ← status + endpoint
│                                                                 │
│  📍 eu-central                          5 / 5 pods              │  ← placement + health
│  💾 postgres → shared-postgres (own card)                       │  ← key dependency (linked)
│                                                                 │
│  Last deploy: 2h ago by Layla     ⏵ View history                │  ← provenance
│                                                                 │
│  [ Open app ↗ ]    [ Settings ]    [ Logs ]    [ Topology ]    │  ← primary actions
└────────────────────────────────────────────────────────────────┘

States via the status badge:

State	Meaning
● Running (green)	All replicas healthy, traffic flowing
◐ Installing (blue)	Flux reconciling, progress shown inline
◑ Updating (blue)	Config or version change rolling out
◒ Degraded (amber)	Partial — 3/5 pods, 2 unhealthy
◓ Failed (red)	Install or update failed, "View error" button
○ Paused (grey)	Manually paused, scale-to-zero
◔ Pending approval (purple)	Promotion PR open, awaiting reviewers

Clicking the card opens the detail page with tabs: Overview, Settings, Topology, Secrets, Observability, History, Manifests.

The Topology tab is where Placement edits happen — single-region → active-active, region picker, failover policy. The Manifests tab is the Monaco IaC editor.

---

6. Catalog vs Applications-in-use view

6.1 Marketplace (catalog)

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  🌐 WordPress   │  │  💬 Rocket.Chat │  │  🏪 ERPNext     │
│  Self-hosted    │  │  Team chat      │  │  ERP suite      │
│  CMS            │  │                 │  │                 │
│                 │  │                 │  │                 │
│  ⭐ Popular     │  │                 │  │  💼 Business    │
│  [ Install ]    │  │  [ Install ]    │  │  [ Install ]    │
└─────────────────┘  └─────────────────┘  └─────────────────┘

Card here = Blueprint card (something to install). Visually distinct from Application cards.

6.2 Blueprint detail page (cross-Environment view of Applications using a Blueprint)

Blueprint: bp-wordpress @ available 1.4.0                         [⋮]
─────────────────────────────────────────────────────────────────────
Self-hosted CMS. Owner: vendor (openova).  Latest: 1.4.0

Applications using this Blueprint in your Org (4)

  Application       Environment        Version    Status
  ─────────────────────────────────────────────────────
  marketing-site    acme-dev           1.4.0      ● Running   [Open]
  marketing-site    acme-stg           1.3.0      ● Running   [Open]
  marketing-site    acme-prod          1.2.0      ● Running   [Open]
  blog              acme-prod          1.2.0      ● Running   [Open]

[ + Install in another Environment ]    [ Compare versions ]

This is the "where is this Blueprint running in my Org" view — the simplest cross-Environment surface. No chain object; just a query.

6.3 Environment view (where the cards live)

Environment: core-banking-prod               [+ Install]  [⋮ View modes ▼]

  Group by: ( Status ▼ )    Filter: [_______]    [List | Grid]

  ─── Running (12) ───────────────────────────────────────────
  [ marketing-site card ]  [ blog card ]  [ payment-rail card ]  …

  ─── Updating (1) ───────────────────────────────────────────
  [ analytics-api ◑ updating to 2.3.0 ]

  ─── Degraded (1) ───────────────────────────────────────────
  [ notification-bus ◒ 2/3 pods, restart pending ]

  ─── Backing services (4) ──────────────────────────────────
  [ shared-postgres ]  [ shared-redis ]  [ kafka-cluster ]  [ object-store ]

Backing services (Postgres, Redis, etc.) get their own section so users see infrastructure-as-Applications principle (one of the architectural commitments). Clicking a card surfaces dependents (Used by: marketing-site, blog, analytics-api).

---

7. Differences in default UI mode by Sovereign type

Setting	SME-style (Omantel) default	Corporate default (Bank Dhofar)
Console default depth	Form view	Advanced view + IaC editor toggle on
Developer mode (Blueprint Studio)	Hidden, off	Visible by role
Multi-Environment promotion features	Hidden when only 1 Env	Visible always
EnvironmentPolicy editor	Hidden by default	Visible by role
kubectl access for users	Off	On for org-developer and above
Git access for users	Off (sovereign-admin can flip per-Org)	On
Marketplace features (search, bundles, ratings)	All on	All on but de-emphasized
Specter / AIOps Blueprint included by default	Optional	Recommended (Cortex + Specter on top)

Each Sovereign sets its defaults at provisioning time; users within can override via per-user preferences within the role permissions allowed.

---

Cross-reference GLOSSARY.md and ARCHITECTURE.md for the underlying model.