# ai-helm

GitOps source-of-truth for the Camer Digital AI platform — Helm charts for
every workload that runs in the cluster, plus the ArgoCD `Application` /
`ApplicationSet` manifests that wire them together.

> **Companion repo:** `ai-gitops` holds the cluster-/environment-specific
> overrides (image tag pins, per-env values overlays, ArgoCD secret-store
> wiring). This repo is the chart source; `ai-gitops` is the deployment
> state. See [ADR-0010 / ADR-0013](docs/adr/) for the rationale and the
> deferral of write-back automation between them.

## Layout

```
.
├── charts/                     Helm charts. Each subdirectory is one chart.
│   ├── apps/                   The "umbrella" — emits ArgoCD Application
│   │                           manifests for every other workload. The
│   │                           entry point ArgoCD points at.
│   ├── ai-models/              Orchestrator (ApplicationSet) for the AI
│   │                           gateway model fleet. ADR-0012.
│   ├── ai-model/               Leaf: one AIGatewayRoute + BackendTraffic-
│   │                           Policy per model.
│   ├── ai-models-backends/     Leaf: shared Backend + AIServiceBackend +
│   │                           security/TLS policies for the upstream
│   │                           backends (Fireworks, DeepInfra, Google AI Studio).
│   ├── librechart/             Orchestrator (ApplicationSet) for LibreChat
│   │                           and adjacent components. ADR-0014.
│   ├── librechat-app/          Leaf: LibreChat + MongoDB.
│   ├── librechat-search/       Leaf: Meilisearch.
│   ├── librechat-opencode-wellknown/
│   │                           Leaf: nginx serving the opencode .well-known
│   │                           JSON. ADR-0014.
│   ├── core-gateway/           Envoy AI Gateway (Gateway, EnvoyProxy,
│   │                           access-log, traces collector). The data
│   │                           plane.
│   ├── kuadrant-policies/      Authorino AuthConfig + SecurityPolicy
│   │                           (ADR-0003, ADR-0005, ADR-0011).
│   ├── observability-dashboards/
│   │                           Grafana operator CRs (Grafana external-mode,
│   │                           Folders, Dashboards) — ADR-0004.
│   ├── cert/                   cert-manager ClusterIssuers + the self-signed
│   │                           internal CA chain.
│   ├── external-secrets/       ESO ClusterSecretStore + RBAC.
│   ├── keycloak-baseline/      Keycloak realm config (clients, scopes,
│   │                           groups, roles) via keycloak-config-cli.
│   ├── common/                 Bitnami common library — helpers used by
│   │                           every first-party chart.
│   └── …                       (mcps, mcpo, lmcache, model-deployment,
│                                models-proxy, *-backup, …)
│
├── tools/
│   └── dashboards/             Python dashboard generator (grafana-foundation-sdk,
│                                uv + ruff). ADR-0008.
│
├── docs/
│   ├── adr/                    Architecture Decision Records (ADR-0001..0014).
│   │                           Start here when asking "why?".
│   ├── README.md               Index of every doc.
│   └── …                       Subsystem docs, migration notes, runbooks.
│
├── .github/workflows/          CI: helm-lint, dashboards-drift, opencode
│                                review, release-helm-charts, security scan.
└── .gitlab-ci.yml              Mirror of the opencode review for GitLab.
```

## Parked: image-gen-mcp-rs

[`ADORSYS-GIS/image-gen-mcp-rs`](https://github.com/ADORSYS-GIS/image-gen-mcp-rs) (a
multi-provider image-generation MCP server) was evaluated for a sixth `charts/mcps`
route and deliberately **not** wired ([Story #991](https://github.com/ADORSYS-GIS/ai-helm/issues/991)):

- Image generation is already delivered by the self-hosted **Z-Image-Turbo** on the
  GPU fleet (LocalAI, ADR-0100/0102) via LibreChat's `IMAGE_GEN`.
- The server is a full major + 7 minors behind its core deps (`rust-mcp-sdk` 0.9→1.0.1,
  `async-openai` 0.34→0.41.3) — see [image-gen-mcp-rs#41](https://github.com/ADORSYS-GIS/image-gen-mcp-rs/issues/41).
- Its default providers are external SaaS (OpenAI / Gemini), not the platform's
  self-hosted path.

Revisit only if a consumer needs **agent-side** image generation **and** #41 lands.

## Where to start

| You want to… | Read this |
|---|---|
| Understand the system at a glance | [`docs/architecture.md`](docs/architecture.md) |
| See every architectural decision and why | [`docs/adr/README.md`](docs/adr/README.md) |
| Contribute a change | [`CONTRIBUTING.md`](CONTRIBUTING.md) |
| Audit chart pin currency vs upstream | [`docs/migrations/2026-currency-audit.md`](docs/migrations/2026-currency-audit.md) |
| Add a new dashboard | [`docs/playbooks/grafana-operator-and-dashboards.md`](docs/playbooks/grafana-operator-and-dashboards.md) + [`docs/playbooks/python-dashboard-generation.md`](docs/playbooks/python-dashboard-generation.md) |
| Understand the gateway auth flow | [`docs/patterns/per-user-observability.md`](docs/patterns/per-user-observability.md) + [`docs/adr/0011-oidc-downstream-headers.md`](docs/adr/0011-oidc-downstream-headers.md) |
| Use the AI gateway from a CLI | [`docs/integrations/opencode-well-known.md`](docs/integrations/opencode-well-known.md) |
| Operate the LGTM stack | [`docs/playbooks/observability-stack.md`](docs/playbooks/observability-stack.md) |
| Restore a backup | [`docs/cnpg-native-backup/`](docs/cnpg-native-backup/), [`docs/playbooks/mongodb-restoration-guide.md`](docs/playbooks/mongodb-restoration-guide.md) |

## The big picture in three sentences

1. **`charts/apps`** is the GitOps root; ArgoCD points at it. It emits one
   `Application` per workload — most pointing at other charts in this
   repo, some at upstream OCI/HTTPS chart repos.
2. **Two patterns** govern how complex charts are split: a single chart
   that renders directly (small charts), or an **orchestrator chart that
   renders an `ApplicationSet` fanning out to leaf charts** (ai-models,
   librechart — ADR-0012 and ADR-0014).
3. **Observability is unified**: every signal (metrics, logs, traces)
   funnels through Alloy into Mimir/Loki/Tempo and surfaces in Grafana.
   The AI gateway emits structured access logs that carry per-user
   attribution (Authorino → headers → Loki labels — ADR-0005, ADR-0011)
   so dashboards segment by user / repo / CI run.

## Conventions

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full set. Highlights:

- **uv + ruff** for any Python tooling we ship (ADR-0008).
- **ADR for any non-obvious architectural choice** (`docs/adr/`,
  Michael Nygard format). Immutable once accepted; supersede with a
  new ADR rather than editing.
- **Commit messages**: conventional-commits style (`chore`, `feat`,
  `fix`, `refactor`, `docs` scopes).
- **Branch names**: feature work on `<topic>/<short-name>` or
  `<issue>-<topic>`; never push to `main` directly.
- **Helm chart pins**: explicit semver or commit SHA. No `:latest`,
  no `'*'` (audit findings; ADRs cover the few intentional exceptions).
- **Dashboard JSON** is generator-emitted (Python under
  `tools/dashboards/`). Hand-written JSON is allowed for one-offs but
  flagged in the per-dashboard README.

## License

[MIT](LICENSE).

## Maintainer

@stephane-segning (Stephane Segning Lambou).