feat(claude): first CLAUDE.md (#226)

2026-09-30 13:33:00 +08:00 · 2026-06-29 17:34:29 +00:00
parent b723285626
commit 745bf5970e
1 changed files with 173 additions and 0 deletions
@@ -0,0 +1,173 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+Yucca is a multi-tenant **backup service**: OIDC-authenticated users get S3-backed
+[restic](https://restic.net/) repositories. The repo is two things at once:
+
+- **Application** (`packages/`) — the NestJS/Go/Svelte services that run the product.
+- **Infrastructure** (`tf/`, `ansible/`, `kubernetes/`, `charts/`) — everything that
+  operates Yucca: Ceph object storage, Talos K8s, Flux GitOps, networking. See the
+  table in `README.md` and the per-directory `README.md` files; each infra subtree is
+  largely self-contained.
+
+## Tooling model
+
+Everything is driven through **[mise](https://mise.jdx.dev/)** tasks, not raw `pnpm`/`go`.
+Task definitions live in `.mise/tasks/` (shell scripts, hierarchical: `web/test/_default`
+is `mise run web:test`) and `.mise/config.toml` (the `[tasks.*]` aggregate tasks + tool
+pins). `mise` also pins every binary version (node, pnpm, go, kubectl, helm, tilt, opentofu,
+ansible, etc.) — do not assume a tool is on PATH outside of mise.
+
+Package manager is **pnpm workspaces** with a **catalog** (`pnpm-workspace.yaml`): dependency
+versions are centralized there and referenced as `"catalog:"` in each `package.json`. Add/bump
+shared deps in the catalog, not in individual packages.
+
+Secrets come from **1Password** via `op run`. Tasks that need secrets wrap commands in
+`op run --env-file=... --`; `.env` files contain `op://` references, never literal secrets.
+`OP_ACCOUNT` is set in `.env` (copy `.env.example`).
+
+## Common commands
+
+```bash
+# Compose-based dev (fastest inner loop): postgres, minio, mock-oidc, victoria-* in Docker
+mise dev                  # install deps, build common, start docker infra, run all *:dev
+mise <pkg>:dev            # run one service, e.g. mise web:dev, mise yucca-api:dev
+
+# Quality gates (what CI runs)
+mise check                # lint + format check + svelte-check + unit tests (= the `checks` CI job)
+mise fix                  # autofix lint/format + lingui extract
+mise lint / mise format   # individually
+mise build                # build all packages
+
+# Tests
+mise test                 # all unit tests (jest per NestJS pkg, vitest for web)
+mise test:integration     # all integration tests (runs --jobs 1; needs infra up)
+mise test:e2e             # e2e (jest suites) — needs the stack running
+mise test:e2e:web         # web Playwright e2e
+mise <pkg>:test           # one package's unit tests, e.g. mise yucca-api:test
+mise yucca-api:test -- -t "name of test"   # single test (args after -- go to jest)
+mise yucca-api:test:watch # watch mode
+
+# Database migrations (yucca-api owns the schema)
+mise yucca-api:migrations <args>   # wraps @immich/sql-tools against the dev DB
+```
+
+### k3d + Tilt (prod-shaped dev)
+
+The alternative dev flow that mirrors prod topology (Helm, CloudNativePG, Rook-Ceph, in-cluster DNS):
+
+```bash
+mise k3d:up      # create local k3d cluster + registry
+mise tilt:up     # build images, render charts from kubernetes/apps/dev/local, port-forward, live_update
+mise tilt:down
+mise k3d:down
+```
+
+CI uses the same path: `mise tilt:ci-infra` (infra only, apps run on the runner) for integration
+tests, `mise tilt:ci` (full stack) for e2e. See `Tiltfile` (extensively commented) — Tilt's source
+of truth is the Flux tree under `kubernetes/`, not a separate manifest.
+
+Forwarded ports: `5173` web · `3020` yucca-api · `3030` yucca-admin-api · `3010` michael ·
+`8092` mock-oidc · `9000` ceph rgw (S3) · `8428` victoria-metrics · `9428` victoria-logs.
+
+### Infrastructure (terragrunt / ansible)
+
+```bash
+mise tf:plan / tf:apply / tf:init / tf:destroy   # terragrunt for a stack (TF_STACK_DIR=tf/deployment/<partition>/<region>/<stack>)
+mise tf:fmt
+mise k8s:validate        # helm template + kubeconform + flux-local build of the whole k8s tree (CI gate, no cluster)
+mise mgmt:render-inventory / mgmt:ansible        # render + converge management hosts
+```
+
+`tf:*` wrap terragrunt in `tf/op-run.sh` (injects the 1P superuser token from `tf/.env`).
+
+## Application architecture
+
+**Backend services are NestJS 11 + TypeScript**, sharing patterns: controllers → services →
+repositories (data access), Zod-validated `env.ts`, JWT auth guards via an `@AuthRoute()`
+decorator, and observability from the shared `@common/server` package. Each service imports
+`@common/server/otel` at bootstrap to init the OpenTelemetry SDK (pino logs, OTLP traces/metrics
+to victoria-*).
+
+| Service | Lang | Role |
+|---|---|---|
+| `yucca-api` | NestJS | User-facing API. Owns auth (OIDC code + device flow, ES256 JWTs), repositories, **the database schema + migrations**. |
+| `yucca-admin-api` | NestJS | Admin API (user/session/repository management). Shares the same DB + JWT validation. |
+| `michael` | Go | **Production** restic REST backend — S3 proxy implementing restic's HTTP protocol, with JWT (ECDSA pubkey) verification, WORM enforcement, multi-backend pool/DNS load-balancing. Deployed in k8s (`kubernetes/apps/base/michael`). |
+| `restic-api` | NestJS | Earlier TypeScript implementation of the same restic backend, kept as a **reference** (`mise restic-api:dev-reference`); not in the deployed app set. |
+| `yucca-metrics-worker` | NestJS | Cron worker (every 5 min): reads bucket usage from RadosGW, writes meter tables, emits OTel gauges. |
+| `mock-oidc-provider` | Node | Dev/test OIDC IdP (code + device flow). Used by compose and k3d when no real issuer is configured. |
+| `common` (`@common/server`) | TS lib | Shared OTel init, pino logger repository, logging interceptor. |
+
+**Frontend** (`packages/web`) is **SvelteKit 5 + Tailwind 4**, using `@immich/ui`, lingui i18n
+(`mise web:lingui:*` to extract/compile — compiled locales are generated, not edited), and the
+generated API client. It also embeds the orchestration UI (`@futo-org/backups-orchestrator-ui`).
+
+**`packages/yucca-sdk/`** is a separately-versioned product: `orchestration-api` (NestJS) +
+`orchestration-ui` (SvelteKit). Not in the pnpm workspace glob's `packages/*` alone — note
+`packages/yucca-sdk/*` is added explicitly in `pnpm-workspace.yaml`.
+
+### API client generation (don't hand-edit generated files)
+
+`yucca-api` controllers/DTOs (via `@nestjs/swagger`) → `mise yucca-api:sync-openapi` writes
+`openapi-specs.json` → `mise yucca-api-client:build` runs `oazapfts` to generate
+`packages/yucca-api-client/src/fetch-client.ts` (published as `@futo-org/backups-api-client`,
+consumed by web). `fetch-client.ts` is generated (eslint-ignored). When you change an API
+contract, regenerate rather than editing the client.
+
+### Database
+
+PostgreSQL accessed via **Kysely**. The schema lives in `packages/yucca-api/src/schema/`
+(`tables/` definitions, `migrations/` SQL run through `@immich/sql-tools`). `yucca-api` is the
+schema owner; other services read the same DB.
+
+### Go services
+
+`michael` and `yuctl` are Go 1.25, `module <name>` + `internal/<pkg>`, `aws-sdk-go-v2` for S3,
+`rs/zerolog` for logs. `yuctl` (`packages/yuctl`, cobra CLI) is the operations CLI: it reads the
+Terraform **discovery** contract from S3 state (no terragrunt/checkout) to resolve the
+partition→region→{k8s, ceph} topology and drive day-2 ops. See `packages/yuctl/README.md`.
+
+## Infrastructure architecture
+
+The whole fleet is modeled as **partition → region → { exactly one K8s cluster, one-or-more
+Ceph clusters }** (introduced in #222; replaced the older env/site terms). Partitions: `prod`,
+`staging`, `dev`. Regions e.g. `htz-fsn1`, `austin`, `local`, plus a `global` pseudo-region for
+account-wide stacks. Slug = `<partition>-<region>`.
+
+- **`tf/`** — OpenTofu + Terragrunt, authoritative for cluster identity, 1P secret items, and
+  rendered Ansible inventories. Layout: `deployment/<partition>/<region>/<stack>/`; shared logic
+  in `shared/modules/` (ceph-cluster, talos-cluster, talos-baremetal, identity, fabric-addressing,
+  netbird-env, fabric/switch config). Every stack emits a non-sensitive **`discovery` output**
+  (the contract `yuctl`/k8s/ansible consume); all secrets in it are `op://` refs. `render/` renders
+  Ansible inventories.
+- **`ansible/`** — three subtrees: `ceph/` (cephadm bare-metal clusters), `talos/` (Talos K8s as
+  libvirt VMs on the Ceph hypervisors — VM provisioning only; talosctl gen/bootstrap is owned by
+  the TF siderolabs provider), `mgmt/` (Hetzner management hosts + NetBird routing). Roles are
+  gated by `*_enabled` flags.
+- **`kubernetes/`** — **Flux GitOps**. `clusters/<partition>/<region>/` are entry points;
+  `apps/{base,<overlays>,dev/local}/` hold HelmReleases; `components/{infra,apps,roles}/` are
+  Kustomize Components selected per role (primary/secondary). Three config layers merged via
+  postBuild: `cluster-settings.generated.yaml` (TF-rendered), `cluster-settings.yaml` (human),
+  `image-versions` (CI). Tilt reads `apps/dev/local/`.
+- **`charts/`** — in-repo Helm charts. `lib/yucca-common` is a library chart (shared deployment/
+  service/secret templates); `apps/<svc>` are per-service charts depending on it; `platform/` for
+  rook/cnpg/objectuser. Service names are pinned via `fullnameOverride` so in-cluster DNS is
+  identical whether Tilt or Flux renders them.
+
+Deploy flow on merge to main: CI builds images tagged `0.0.<run_number>` → Flux auto-promotes the
+highest tag to staging → production is gated behind a reviewed `promote-production` job.
+
+## Conventions
+
+- **Conventional commits** are enforced on PRs (`feat(scope):`, `fix(scope):`, `chore:`).
+  Common scopes: `ceph`, `netbird`, `michael`, `yucca-api`, `ansible`, `bgp`. Releases are
+  automated via release-please (`chore(main): release …` PRs); the monorepo is single-versioned.
+- ESLint flat config (`eslint.config.mjs`) is strict on promises: `no-floating-promises`,
+  `no-misused-promises`, `require-await`, `await-thenable` are all errors. Prettier: single quotes,
+  trailing commas, width 120.
+- Generated files are eslint-ignored: `**/fetch-client.ts`, `packages/web/src/locales`, `dist`,
+  `build`, `.svelte-kit`.