# Architecture diagram catalogue

This catalogue maps each logical diagram to its source, generated SVG, operating
question, and evidence boundary. Mermaid files in `sources/` are authoritative;
SVGs in `generated/` are review artifacts. A diagram describes a system or
procedure only to the extent stated on its accompanying page.

| Diagram | Operational scope | Source → output | Boundary and omissions |
| --- | --- | --- | --- |
| Engineering Landscape | Public delivery, local platform, automation, and configured Google Cloud and Oracle Cloud recovery services | `engineering-landscape.mmd` → `engineering-landscape.svg` | Logical trust boundaries; no IDs, addresses, credentials, or claim that every depicted component is continuously healthy |
| Hybrid-Cloud Platform | Static deployment, encrypted configuration export, management, and monitoring planes | `hybrid-cloud.mmd` → `hybrid-cloud.svg` | Firebase, k3s, WIF, private storage, and controls; no provider identifiers or keys |
| OCI Kubernetes DR | Encrypted controlled-workload backup, OCI governance, isolated restore, and incomplete operational controls | `oci-k3s-dr.mmd` → `oci-k3s-dr.svg` | Status-labeled evidence boundary; no cloud identifiers, credentials, private topology, backup contents, or broader recovery claim |
| Heterogeneous GPU Inference | API, job state, queues, Intel and AMD worker paths, runtime model storage, and observability | `dual-gpu-ai-orchestrator.mmd` → `dual-gpu-ai-orchestrator.svg` | Hosted checks and configuration only; no claim of GPU execution, throughput, model quality, or production rollout |
| k3s Platform | Control plane, runtime, ingress, workloads, storage, and backup relationships | `k3s-platform.mmd` → `k3s-platform.svg` | Logical node roles; no node names, IPs, kubeconfig, or workload data |
| Request Path | DNS/TLS/MetalLB/Traefik/Service/EndpointSlice/Pod diagnosis | `request-path.mmd` → `request-path.svg` | Troubleshooting sequence; no hosts, certificates, addresses, or current findings |
| Service Path Analyzer | Analyzer stages and detectable conditions | `service-path-analyzer.mmd` → `service-path-analyzer.svg` | Tool behavior and examples; no claim that an example condition exists now |
| Backup and Restore | Backup evidence, archive inspection, and controlled restore gates | `backup-restore.mmd` → `backup-restore.svg` | Allowlisting, retained-field risk, encryption, and operator gates; no keys, object names, or restore claim |
| DR Dependencies | Recovery order and dependency risks | `dr-dependencies.mmd` → `dr-dependencies.svg` | Generic analyzer patterns; no live defect or measured recovery time |
| CI/CD Workflows | Static and container delivery transitions | `ci-cd.mmd` → `ci-cd.svg` | Branch, validation, artifact, and deployment gates; no tokens, runner hosts, or proof every job passed |
| Cluster Lifecycle | Ordered startup, shutdown, and escalation points | `cluster-lifecycle.mmd` → `cluster-lifecycle.svg` | Procedure flow; no schedule, host address, or execution record |
| Observability | Metrics, logs, probes, dashboards, alerts, and action | `observability.mmd` → `observability.svg` | Signal ownership; no live values, retention guarantee, or notification identifier |
| Security and Identity | Source, cluster, public, and cloud trust boundaries | `security-controls.mmd` → `security-controls.svg` | Authentication and least privilege; no identities, tokens, keys, or current IAM inventory |
| Storage | Replication, application backup evidence, off-site configuration, and restore targets | `storage.mmd` → `storage.svg` | Distinct protection layers; no disk, object, or application-data contents |
| Terraform Ownership | Terraform, manifests, CI, manual, external, and legacy ownership | `terraform-ownership.mmd` → `terraform-ownership.svg` | Change ownership; no state contents, provider IDs, or live drift conclusion |
| Project Relationships | Content map from projects to engineering topics | `project-relationships.mmd` → `project-relationships.svg` | Editorial relationships only; no runtime dependency or system-state claim |

## Operating and trust boundaries

The repository owns Mermaid sources, public-safe descriptions, and generated
artifacts. Operators own runtime checks, approvals, and restore execution.
External DNS, Firebase, Google Cloud accounts, and notification destinations
remain outside the repository boundary. Red or warning nodes describe failure
paths to investigate; they are not current incidents unless a dated page says
otherwise.

## Verification and maintenance

The catalogue was reviewed on 24 July 2026 against repository workflows,
Terraform and Kubernetes configuration, project data, public GitHub checks,
Firebase routes, the live k3s API, and aggregate GCP/OCI inventories. The
current k3s evidence includes both Ready components and disclosed Git-source,
new-node storage, and off-site backup degradation. Cloud identifiers, policy
contents, credentials, and secret values remain omitted; older archive and
restore execution evidence retains its original date.

The OCI Kubernetes DR diagram was reviewed on 23 July 2026 against
the project's Terraform, Kubernetes manifests, backup and restore tooling,
tests, Git state, and sanitized reports. Those reports support one applied
foundation, encrypted controlled-workload backup, and isolated restore. The
duplicate Terraform variable was reconciled; provider-backed validation and
the repository safety suite now pass without changing the bounded recovery
claim.

The heterogeneous GPU diagram was reviewed on 24 July 2026 against the public
repository and its successful 23 July GitHub Actions runs. It shows the
implemented service and queue contracts while keeping live GPU execution,
model provenance, throughput, and production security outside the verified
boundary.

Run `npm run diagrams:check` after source changes. The check parses SVG XML,
requires non-empty accessible outputs, and scans public artifacts for prohibited
patterns. It checks artifact integrity, not runtime truth.