Skip to main content

C4 System Design — the minicloud Platform

The platform's solution-architecture model — the platform is made of these components, working together like this. Modelled once as a Structurizr DSL (workspace.dsl) and rendered to C4-model diagrams — diagram-as-code, so it never drifts. Every relationship is verified against the GitOps manifests (no invented edges).

Boundary: this models the Platform — the shared technical capabilities (the internal cloud provider). The Information System (the insurer's business apps) appears as a single external consumer and gets its own C4 model later. See the Architecture Hub for how the two pillars relate.

Two lenses, same facts. Each view is shown as the icon-rich visual (brand logos + verb-labelled edges, mingrammer diagrams); the equivalent formal C4 notation (Structurizr, standard boxes) is linked beside it. Click any diagram to open it full-screen. The complementary capability map, technology topology and physical view live on Platform Architecture.

Jump to · ① Context · ② Container · ③ Deployment · ④ Subsystem deep-dives

① System Context — who the platform talks to​

The platform as one system, its users, the external systems it depends on, and the Information System as its consumer.

C4 System Context — minicloud Platform

Formal C4 notation (Structurizr): Context diagram →.

② Container — the complete platform (all capabilities)​

The whole platform in one view: every capability as a container, grouped (Access & Networking · Delivery/GitOps · Security & Secrets · Data & Messaging · Storage & Backup · Observability · AI Runtime · Runtime & Tooling), with the relationships that make it work — code→production (Delivery), request→app (Access), secrets, telemetry, backup, and what the IS consumes. It's detailed — click to open full-screen and zoom.

C4 Container view — the complete minicloud Platform

Formal C4 notation (Structurizr): Container diagram →.

Drill into a subsystem → GitOps / ArgoCD · Secrets / Vault+ESO · AI / LiteLLM — or follow a flow: delivery · request · observability.

③ Deployment — where it physically runs​

The same model, deployed: the 6-node k3s cluster + the off-cluster MAAS controller, with placement (Vault → fast-heron, vLLM → star-kitten, control-plane → set-hog) and Longhorn replicated across the storage nodes.

C4 Deployment view — 6-node k3s + controller

Subsystem deep-dives (C4 Component + flow)​

Zooming inside the key containers — "the GitOps platform in detail", and the same for secrets and the AI gateway. All grounded in the GitOps manifests + the platform rules. (Click any diagram to enlarge.)

↑ Back to the Container view

How code reaches production — the delivery flow​

A git push to a running production workload (CI → registries → Kargo → ArgoCD → cluster), showing the continuous-delivery vs continuous-deployment split: the same artifact is built+proved once, Kargo auto-deploys it to dev (continuous deployment — no human), then a CODEOWNERS-gated PR promotes it to prod (continuous delivery — a human decides when). The full narrative is on the Delivery Workflow page.

System-design view — icon-rich, the four stages colour-coded (grey build · cyan promote · green = automatic dev · amber = human-gated prod). Open full SVG →

Delivery pipeline — continuous delivery (prod) + continuous deployment (dev)

Formal C4 dynamic view — the same sequence in standard C4 notation (Structurizr). Open full SVG →

Delivery flow — how code reaches production

The GitOps workflow system (the reconcile loop)​

The whole GitOps system in one view — where the delivery flow follows the artifact, this follows the control loop: humans and Kargo only ever write to Git (the single source of truth); ArgoCD is the only thing that writes to the cluster, continuously reconciling desired state (Git) against live state and self-healing drift. Shows the two-repo model, Kargo promotion (dev auto / prod CODEOWNERS-gated) into Git, the app-of-apps tree, the Helm wrapper+library render, and the drift-correction loop (red). Open full SVG →

GitOps workflow system — Git is the source of truth, ArgoCD is the only cluster writer

GitOps delivery — inside ArgoCD​

Zooming inside the reconcile engine above: Root App-of-Apps → ApplicationSets / AppProjects → Sync+Health controller → the cluster; Kargo opens the CODEOWNERS-gated PR.

C4 Component — inside ArgoCD

Secrets delivery — inside Vault + ESO​

Vault KV/PKI (KMS auto-unseal) → ESO ClusterSecretStore reads Vault → ExternalSecret renders the k8s Secrets workloads consume.

C4 Component — inside Vault + ESO

AI gateway — inside LiteLLM​

Virtual keys/budgets → model router → PII guardrail (Presidio) + cache + provider connectors (vLLM / Groq / cloud).

C4 Component — inside the LiteLLM gateway

How a request reaches an app (networking flow)​

User → Cloudflare → tunnel → ingress → Authentik (forward-auth) → the workload.

Request flow — how a user request reaches an app

Telemetry + alerting (observability flow)​

Prometheus scrapes the cluster · OTel ships logs→Loki / traces→Tempo · alerts → Alertmanager → SES email.

Observability flow — telemetry + alerting

Further subsystem views are cheap to add — the model already holds the elements; just add a component/dynamic view to workspace.dsl.

Legend​

  • Shapes (C4): rounded person = a Person; blue box = the Platform (software system); grey box = an external system; purple box = the Information System (the platform's consumer); teal/coloured boxes = containers (platform capabilities, tinted by group).
  • Arrows: every arrow is a relationship with a verb (builds · pushes · promotes · reconciles · supplies-secrets · issues-certs · authenticates · scrapes · ships-logs · backs-up · routes-to · consumes).
  • Each formal view also has a C4 key (auto-generated): structurizr-<view>-key.svg.

Maintaining it​

Edit diagrams/structurizr/workspace.dsl, run make c4 (Structurizr CLI → PlantUML → SVG, via Docker), commit the refreshed SVGs — a CI workflow also regenerates on change. This is the single source of truth for the platform's C4 views; the capability map / technology topology / physical view remain the complementary stylistic references.