desi_explorer/AGENTS.md

AGENTS.md

Odin + raylib interactive 3D universe map (DESI data), a Rust + axum API, with Go + Pulumi infra and Gitea Actions CI. A clean odin build + cargo test + go test is the verification step.

Commands

The root Makefile is a lean delegator: base commands (run, build, test, ...) forward into the per-project Makefiles in gui/, api/, and infra/. Project-specific commands are reached via make -C <dir> <target>.

• Run: make run; Build: make build (-> bin/desi_explorer); Web: make build-web (Emscripten/WASM -> build/web); Debug: make build-debug; Run Web: make run-web (WASM build + API server)
• Test: make test (runs odin test in gui/, cargo test in api/, go test in infra/); Clean: make clean; Format: make fmt
• API: make api-run, make api-test, make api-check (thin passthroughs to make -C api <target>)
• Setup: make setup (submodules + gui lib/local + cargo fetch + go mod tidy in infra/)
• Add dependency: make -C gui add-dep DEP=<name> (searches Codeberg/GitHub/GitLab, adds as submodule to gui/lib/local/)
• Infra: make infra-preview, make infra-up, make infra-down, make infra-refresh (passthroughs to make -C infra <target>)
• Renovate: make renovate-validate (npx renovate-config-validator)
• Format Odin with odinfmt (config gui/odinfmt.json: tabs, width 80); format Rust with cargo fmt

Layout

• gui/ — the Odin + raylib renderer. gui/src/main.odin is the entrypoint (loop is update() → draw(); resizable window with an orbital Camera3D; point cloud generated procedurally in make_universe). gui/lib/ holds third-party Odin deps (see below), gui/www/ the Web GUI (WASM shell / static web assets), and gui/scripts/ the build scripts. gui/Makefile owns the Odin targets.
• gui/lib/ — third-party Odin deps (submodules / vendored libs). raylib is not here: it ships vendored with Odin and is imported as vendor:raylib. gui/lib/local/ is the default -collection:lib target and is currently empty.
• api/ — Rust + axum backend API that will serve DESI catalog data. src/lib.rs exposes routes/models/config; src/main.rs is the server entrypoint (binds API_BIND_ADDR, default 0.0.0.0:8080). Crate name is desi-explorer-api (lib desi_explorer_api); Rust version pinned in api/rust-toolchain.toml. api/Makefile owns the Rust targets.
• infra/ — Go + Pulumi (runtime: go) targeting the on-prem k3s cluster via the default kubeconfig, mirroring the homelab repo's pattern. Module name is desi-explorer-infra. infra/Makefile owns the Pulumi/Go targets.
• scripts/ — repo-level build helpers (Odin toolchain install).
• .gitea/workflows/ — ci.yml (PR: odin test + build, cargo test + clippy, go test + vet; infra always runs tests/vet and posts a pulumi preview --diff as a PR comment when infra/gui/api changed) and release.yml (tag v*: build native + WASM + publish a Gitea release).

Conventions

• Odin code lives in gui/src/; external deps go in gui/lib/ and are wired via -collection:lib=lib/local (or a git submodule imported by relative path).
• Everything is plain make — no Taskfile — so CI (Gitea Actions) can call make directly.
• Keep the renderer (gui/), API (api/), and infra (infra/) logically separated; each owns its own Makefile, and the root Makefile is the only place that ties them together.

Gotchas

• Odin version is pinned in .gitea/workflows/*.yml (ODIN_VERSION) and defaults in scripts/install_odin.sh; bump both together when tracking a new release.
• CI installs clang (Odin uses it as the linker backend) and, for the WASM build, Emscripten + MinGW (Windows cross-build).
• The WASM build uses -define:RAYLIB_WASM_LIB=env.o so emcc links raylib's prebuilt web lib instead of Odin.
• Gitea Actions reuse the GitHub Actions plugin ecosystem (actions/checkout, christopherHX/gitea-upload-artifact / gitea-download-artifact); contexts remain ${{ github.* }}.

Session History

Export session information to resources/ai/sessions at the end of every session — for both plans and builds. (Gitignored.)

Gitignored

bin/, build/, *.bin, *.o, *.log, resources/ai/sessions, infra/Pulumi.*.yaml.backup, api/target/.