abf01b6f21
8 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
hatiyildiz
|
0a6179dd21 |
docs(unified-repo-model): collapse SME and corporate to one shape — Application = Gitea Repo
Architectural correction. Replaces the previous "one Gitea repo per Environment with Apps as folders" rule with a single uniform shape that scales by configuration only: - Catalyst Application = one Gitea Repo (always, regardless of scale) - Branches develop/staging/main map to dev/stg/prod environments - 5 conventional Gitea Orgs per Sovereign: catalog (public mirror), catalog-sovereign (Sovereign-curated private Blueprints), one per Catalyst Organization (with shared-blueprints + N App repos), system (sovereign-admin scope) - EnvironmentPolicy CR lives in system/catalyst-config/policies/, same shape for SME and corporate; only field values differ Removes the SME-vs-corporate dual-shape design that violated the "Application is application" invariant. Teams primitive (proposed for corporate scale) is dropped — team boundaries emerge from CODEOWNERS at the App-repo level. RE-score thresholds and EnvironmentPolicy fields are universal defaults; only their values vary per Org's policy choice. Files updated line-by-line: GLOSSARY (Application + Environment definitions, new Gitea-Orgs section, 6 component-row updates), NAMING §11.2 (Realization 7-bullet rewrite), ARCHITECTURE (§1, §3 topology, §4 write-side ASCII, §7.1+§7.2+§7.3, §8 promotion, §9 multi-App linkage), PERSONAS-AND-JOURNEYS (§2 surfaces, §4.1 Ahmed, §4.2 Layla full rewrite), BLUEPRINT-AUTHORING §1 (catalog-sovereign source location), PLATFORM-TECH-STACK §2.2+§2.3, SECURITY §3, SOVEREIGN-PROVISIONING §5+§8+§10, IMPLEMENTATION-STATUS §5, SRE §14. VALIDATION-LOG entry "Pass 103 — UNIFIED REPO MODEL REFACTOR" captures the architectural correction and acknowledges the prior 102-pass audit anchored on the wrong shape (text-shape consistency was correct; the chosen text-shape was inadequate). Lesson #21 added: text-shape audits don't substitute for architectural review. Verification: zero remaining old-model assertions in canonical docs (grep clean for 'Environment Gitea repo', '/{org}/{org}-{env_type}', 'per-Environment Gitea repos', 'applications/<app>/values', etc.). |
||
|
hatiyildiz
|
9ae1531878 |
docs(pass-39): non-canonical *-staging env_type drift; clickhouse clean
NAMING §2.4 establishes the 3-char env_type form (prod|stg|uat|dev|poc)
but multiple Environment-name examples used the long form `staging`.
ARCHITECTURE.md §8 (Promotion across Environments): 3 instances of
acme-staging (Blueprint detail mockup L287, prose L295, EnvironmentPolicy
sourceEnvironment L310) renamed to acme-stg.
PERSONAS-AND-JOURNEYS.md: 3 instances renamed —
- digital-channels-staging → digital-channels-stg (Layla narrative L126, L135)
- acme-staging → acme-stg (Blueprint detail mockup L230)
Pass 33 fixed Layla's DNS but left the env_type spelling.
Preserved: payment-rail-staging (Application name, free-form per NAMING)
and minimum-replicas-production (Kyverno policy identifier).
ARCHITECTURE.md deep re-scan with Pass 23 lesson (focus on later
sections): §5-§13 substantively clean. §5 explicitly defines <env> as
{org}-{env_type} which retroactively grounds the ws.<env>.> shorthand
Pass 30 noted as "documented shorthand".
platform/clickhouse/README.md: clean. minioadmin literal placeholder
flagged for future security-hardening pass but not Catalyst drift.
|
||
|
hatiyildiz
|
36e371d874 |
docs(pass-33): PERSONAS-AND-JOURNEYS Layla narrative DNS + vcluster name drift
The corporate-narrative section (§4.2 Layla at Bank Dhofar) read fluently but had Catalyst-naming-rule violations stacked through the timeline that Pass 22's banner-style scan missed: - §4.1 step 6: gitea.omantel.openova.io/... — collapsed location-code. - §4.2 09:15 + 10:00: gitea.bankdhofar.local/... — same collapse. - §4.2 11:00: kubectl context "hz-fsn-rtz-prod-bankdhofar" — vcluster named after Sovereign instead of Organization. Per NAMING §1.5, vcluster name = Org name. Layla works on payment-rail in digital-channels Org, so the context is hz-fsn-rtz-prod-digital-channels. - §4.2 16:00: api.bankdhofar.local/... — same DNS collapse, plus tightened the SPIFFE narrative (external Backstage wouldn't normally hold a SPIFFE SVID; clarified that Backstage runs inside the Sovereign in this scenario). platform/vllm/README.md: clean. Lesson recorded in validation log: narrative-style prose is particularly susceptible to "reads fluently → looks fine" inspection bias. Grep for placeholder shapes regardless of how well the prose reads. |
||
|
hatiyildiz
|
4e46559e25 |
docs(pass-22): PERSONAS Environment name fix — drop Sovereign prefix
Pass 22 — drift-detection on PERSONAS-AND-JOURNEYS + platform/librechat.
One real fix.
PERSONAS-AND-JOURNEYS.md §6.3 Environment view example:
- "Environment: bankdhofar-corp-banking-prod" — three-segment form
implying Sovereign-Org-EnvType. But NAMING-CONVENTION §11.1
establishes `{org}-{env_type}` — the Sovereign name is NOT in
the Environment name. The Sovereign is determined by which
Catalyst console you're logged into.
- This same doc's §4.2 (Layla narrative) explicitly says
"Their internal Organizations are `core-banking`, `digital-
channels`, `analytics`, `corporate-it`" — so the Org is
`core-banking`, and the Environment in that Org for production
is `core-banking-prod`.
- Fixed example to `core-banking-prod`.
platform/librechat/README.md: clean. The example
`namespace: ai-hub` is a customer-chosen Application namespace
(illustrative; the actual namespace would be the Cortex Application
name, customer-chosen).
VALIDATION-LOG: Pass 22 entry added.
Refs #37
|
||
|
hatiyildiz
|
f4e99bb882 |
docs(pass-3): normalize muscatpharmacy Org-slug example consistency
PERSONAS-AND-JOURNEYS and SECURITY were using two competing slugs for the same example Organization: - "muscat-pharmacy" (with hyphen) — used as Org name + Environment name in the Ahmed journey narrative. - "muscatpharmacy" (no hyphen) — used as the vcluster name in the same paragraph, and used everywhere else (NAMING-CONVENTION examples, ARCHITECTURE topology diagram, SECURITY SPIFFE ID). NAMING §2.5 allows both spellings (Org slug regex permits hyphens). But within a single example the spelling must be stable, otherwise readers see a contradiction between Org and vcluster names. Normalized to single-token "muscatpharmacy" throughout (matches the predominant usage and produces simpler URLs / paths). Result: all docs now show the same example Org consistently — muscatpharmacy as Org, muscatpharmacy as vcluster, muscatpharmacy-prod as Environment, gitea.omantel.openova.io/muscatpharmacy/muscatpharmacy-prod as Environment Gitea repo. Refs #37 |
||
|
hatiyildiz
|
80b91709e1 |
docs(iter-3-5): purge operator-as-entity, fix Workspace-controller capital, JetStream KV references
ARCHITECTURE (iter 3): - Removed catalystctl from the §4 write-side diagram (it's read-only; presenting it as a write input contradicted §7.4). - "Both tabs read the same Valkey snapshot" → "JetStream KV snapshot" in §5 (Valkey is no longer in the control plane). - §7.4: catalystctl reframed as "may exist as small read-only debug CLI" rather than implying it ships today. - §11 dependency list: added bp-catalyst-provisioning; removed bp-catalyst-crossplane (Crossplane is per-host-cluster infra, not a Catalyst control-plane component); added clarifying note. - §12 CRD list: added SecretPolicy + Runbook (were already in IMPLEMENTATION-STATUS but missing from the principles table). - §2 SME-style description: "SaaS Operator team (Omantel staff)" → "SaaS provider's cloud team" (Operator banned as entity). NAMING-CONVENTION (iter 4): - §5.1 heading "operator domain" → "Sovereign domain". - §7 multi-region diagram: replaced piecemeal Catalyst component list with a deferral to PLATFORM-TECH-STACK §2; added SPIRE server; fixed "per-Org workspaces" → "per-Environment Gitea repos"; added per-host-cluster infrastructure callout. SECURITY (iter 6 — partial; fold into this commit): - "operator-approved" → "sovereign-admin-approved" for DR promotion. - Realm name "catalyst-operator" → "catalyst-admin" (entity-noun scrubbed from the realm naming itself). SOVEREIGN-PROVISIONING (iter 7 — partial): - "single operator's laptop" → "single person's laptop" (avoid "operator" as entity). - "the next operator" → "the next Sovereign provisioning request, regardless of who initiates it". - "catalyst-operator realm" → "catalyst-admin realm" (×2). - Capital-W "Workspace-controller" residuals (3) → "Environment- controller" (replace_all is case-sensitive; previous iter caught lowercase only). PERSONAS (iter 5): - P3 "within a Sovereign Operator team" → "within a Sovereign's operations team". - Two capital-W "Workspace-controller" residuals fixed. SRE (iter 11 — partial): - §13.2 "Workspace-controller stuck" runbook entry → "Environment-controller stuck". Banned-term sweep result post-fix: no `Operator team|role|account| user|admin` anywhere; no capital-W Workspace as Catalyst scope; no Valkey-as-control-plane refs. Refs #37 |
||
|
hatiyildiz
|
2c4902b409 |
docs(iter-1): add IMPLEMENTATION-STATUS, fix wrong-org refs, reconcile monorepo
First validation iteration. Three concrete corrections. 1. Add docs/IMPLEMENTATION-STATUS.md as the bridge between target architecture and current code state. Status legend (✅ / 🚧 / 📐 / ⏸) applied per-component. Catalyst control plane = mostly 📐. Component READMEs = 🚧 (README only, no Blueprint manifests yet). products/axon = ✅ (only product with real code). core/ = 📐 (just .gitkeep). 2. Status banner added to ARCHITECTURE, SECURITY, SOVEREIGN-PROVISIONING, BLUEPRINT-AUTHORING, PERSONAS-AND-JOURNEYS, PLATFORM-TECH-STACK, SRE pointing readers at IMPLEMENTATION-STATUS.md before they treat any described feature as built. GLOSSARY also references it. 3. Architectural decision (Option A — monorepo canonical): - Each platform/<name>/ and products/<name>/ folder is the source of ONE Blueprint, published as ghcr.io/openova-io/<name>:<semver> by CI fan-out from the monorepo root. - BLUEPRINT-AUTHORING.md §1, §2, §13 rewritten to match. - README.md "what's in this repo" rewritten to clarify monorepo + OCI-fan-out shape; no longer claims every directory is a Blueprint in a way that contradicts BLUEPRINT-AUTHORING. Wrong-org fixes (3 places): - docs/PERSONAS-AND-JOURNEYS.md:13 github.com/openova → openova-io - docs/BLUEPRINT-AUTHORING.md:13 github.com/openova → openova-io - docs/BLUEPRINT-AUTHORING.md:404 github.com/openova → openova-io - docs/BLUEPRINT-AUTHORING.md ghcr.io/openova/* (3 refs) → openova-io API group consistency: - All references unified to catalyst.openova.io/v1alpha1 (was mixed v1 / v1alpha1; v1alpha1 is correct since the CRDs are design-stage with no implementation). core/README.md updated to honestly describe the directory tree as "target structure with .gitkeep placeholders" rather than implying the apps/console, apps/projector, etc. binaries already exist. The legacy apps/bootstrap and apps/manager directories are acknowledged as transitional placeholders that will be removed when the new apps/ layout is scaffolded. CLAUDE.md and .claude/project-memory.md updated to put IMPLEMENTATION-STATUS.md second in the read-first ordering. Refs #37 |
||
|
hatiyildiz
|
d51a3fba4d |
docs: add canonical Catalyst documentation set
Six new docs that establish the unified Catalyst model — Sovereign as
deployed instance, Organization as multi-tenancy unit, Environment as
{org}-{env_type} scope, Application as user-facing handle, Blueprint as
unified module+template successor.
- docs/GLOSSARY.md single source of truth for terminology;
every other doc defers to it; banned terms
(tenant, operator-as-entity, module, template,
Backstage, etc.) listed with replacements.
- docs/ARCHITECTURE.md overall Catalyst architecture: control plane
vs application Blueprints, write path
(Git → Flux → K8s + Crossplane), read path
(CQRS via NATS JetStream → projector → SSE),
SPIFFE/SPIRE workload identity, OpenBao
independent Raft per region (no stretched
cluster), Keycloak per-Org (SME) vs
per-Sovereign (corporate).
- docs/PERSONAS-AND-JOURNEYS.md personas × journeys matrix; only
three first-class surfaces (UI, Git, API);
explicit removal of Terraform/Pulumi/CLI as
user-facing IaC; Application card anatomy.
- docs/SECURITY.md identity (workload + user), OpenBao + ESO
credential flow, dynamic credentials with
auto-rotation sidecar, multi-region
OpenBao (independent Raft per region with
async perf replication — explicitly NOT
stretched), rotation policy CRDs, threat
model.
- docs/SOVEREIGN-PROVISIONING.md Phase 0 (catalyst-provisioner +
OpenTofu one-shot) → Phase 1 (Crossplane
adopts) → Phase 2 (self-sufficient Catalyst
control plane); air-gap procedure;
Organization migration; decommission.
- docs/BLUEPRINT-AUTHORING.md Blueprint CRD spec, configSchema,
placementSchema, depends, manifests,
overlays; Crossplane Composition authoring
for non-K8s; signing/publishing pipeline;
public vs private (Org-scoped) visibility;
contribution path.
Refs #37
|