RadiantWave Agent Guide

What This Is

Go kiosk application using SDL2, OpenGL 3.3, SQLite (via GORM), and D-Bus (NetworkManager). Nix flake is the primary build system. CI runs on Forgejo (not GitHub Actions).

Build & Run

Dev shell via direnv (use flake in .envrc). Inside the nix dev shell:

# Build
go build -o bin/radiantwave radiantwave.go

# Run
./bin/radiantwave

# Nix build (CI uses this)
nix build -L

CGO is required (CGO_ENABLED=1). The nix dev shell and flake.nix preBuild set the necessary CGO_CFLAGS and CGO_LDFLAGS for SDL2. Do not attempt a plain go build outside the nix shell — it will fail on missing SDL2 headers.

Tests

Only one test suite exists: internal/mixer/mixer_test.go. Run with:

go test ./internal/mixer/

No lint or typecheck commands are configured in the repo. CI runs go test then nix build -L.

Every bug fix MUST include regression tests. When fixing a bug, write tests that:

Reproduce the exact conditions that caused the bug (should pass with the fix, fail without it)
Verify the correct behavior after the fix
Cover edge cases related to the bug

Do not merge a bug fix without corresponding tests.

Branch Model

dev → main via pull requests. CI workflows are in .forgejo/workflows/:

build-dev.yml: PRs to dev
build-prod.yml: PRs to main

Both run nix build -L on a self-hosted runner (neils-server-runner).

Key Architecture

Entry: rhemawave.go → internal/application.Run()
State machine: internal/application/application.go — FIRST_RUN → NEEDS_INTERNET → NEEDS_EMAIL_ADDRESS → NEEDS_LICENSE_KEY → DOWNLOADING_ASSETS → READY
Pages: internal/page/ — router pattern with page interface (page.go)
DB: SQLite at ~/.local/share/radiantwave/database.sqlite, managed by GORM in internal/db/
Assets: share/radiantwave/ (fonts, shaders, proclamations, tos) — embedded into the binary and provisioned to the data dir at first run
Audio: .wav files are gitignored, downloaded at runtime from files.radiantwavetech.com
Vendor: Dependencies are vendored and committed. Use go mod vendor after adding deps.

Common Pitfalls

The dev_scripts/reset.sh referenced in the nix devShell hook does not exist in the repo.
share/radiantwave/audio/*.wav is gitignored — do not commit audio assets.
The vendor/ directory is committed — always run go mod vendor after go mod tidy.
CI runs on a self-hosted Forgejo runner, not GitHub-hosted runners. Workflows source nix via /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh.
The packaging/ directory contains a kiosk-specific updater script and is not part of the main build.

2.7 KiB Raw Blame History