CLAUDE.md

1# BirdNET-Go Development Guidelines
2 
3## Project Overview
4 
5BirdNET-Go: Go implementation of BirdNET for real-time bird sound identification aimed for non serious birders and home users. Open source project for fun.
6 
7## Quick Navigation
8 
9- **Frontend**: See `frontend/CLAUDE.md` for Svelte 5, TypeScript, UI
10- **Backend**: See `internal/CLAUDE.md` for Go standards, testing
11- **API v2**: See `internal/api/v2/CLAUDE.md` for endpoints
12- **Testing**: See `TESTING.md` for test patterns, testify usage, shared helpers
13 
14**IMPORTANT**: Always read the relevant CLAUDE.md file before working on code:
15 
16- Working on Go code? Read `internal/CLAUDE.md` first
17- Working on frontend? Read `frontend/CLAUDE.md` first
18- Working on API v2? Read `internal/api/v2/CLAUDE.md` first
19- Writing tests? Read `TESTING.md` first - all tests MUST use testify
20- Working with Sentry issues or support dumps? Load the `sentry` skill first
21 
22## Universal Rules
23 
24### Critical Constraints
25 
26- **NEVER expand API v1** - All new endpoints in `internal/api/v2/`
27- **Always lint before commit**: `golangci-lint run -v` (Go), `npm run check:all` (Frontend)
28- **Branch from updated main**: `git pull origin main && git checkout -b feature-name`
29- **No magic numbers/strings** - Use named constants with descriptive names
30- **Settings must support hot-reload** - All settings changed via the UI must take effect immediately without requiring a server restart. Use per-request checks (e.g., dynamic middleware) instead of startup-time branching.
31 
32### Project Structure
33 
34| Path         | Purpose            |
35| ------------ | ------------------ |
36| `/cmd/`      | Viper CLI commands |
37| `/internal/` | Private packages   |
38| `/pkg/`      | Public packages    |
39| `/frontend/` | Svelte 5 UI        |
40 
41## Code Search & Refactoring
42 
43**Use ast-grep instead of grep/sed for code operations** - it's more reliable and syntax-aware.
44 
45### Search Operations
46 
47```bash
48# ❌ Avoid grep for code patterns
49grep -r "function.*async" src/
50 
51# ✅ Use ast-grep - understands syntax
52ast-grep --pattern "async function $NAME($$$) { $$$ }" src/
53 
54# ❌ Complex grep with regex
55grep -r "console\.\(log\|warn\|error\)" src/
56 
57# ✅ Structural pattern matching
58ast-grep --pattern "console.$METHOD($$$)" src/
59```
60 
61### Refactoring Operations
62 
63```bash
64# ❌ Avoid sed for code changes
65sed 's/let \([a-zA-Z]*\) =/const \1 =/g' file.js
66 
67# ✅ Use ast-grep rewrite - syntax-safe
68ast-grep --pattern "let $VAR = $VALUE" --rewrite "const $VAR = $VALUE" src/
69 
70# ✅ Complex refactoring example
71ast-grep --pattern "export let $PROP" --rewrite "let { $PROP } = \$props()" --lang svelte src/
72```
73 
74### Why ast-grep?
75 
76- **Syntax-aware**: Won't break code structure
77- **Language-specific**: Supports TypeScript, Svelte, Go, etc.
78- **Reliable**: Matches semantic patterns, not just text
79- **Safe refactoring**: Preserves code meaning
80 
81**Frontend**: See `frontend/doc/AST-GREP-SETUP.md` for complete ast-grep integration guide.
82 
83## Build Commands
84 
85| Command               | Purpose                             |
86| --------------------- | ----------------------------------- |
87| `task`                | Default build (auto-detects target) |
88| `task dev_server`     | Development with hot reload         |
89| `task frontend-build` | Frontend only                       |
90| `task clean`          | Clean artifacts                     |
91| `task linux_amd64`    | Cross-platform builds               |
92 
93## Pre-Commit Checklist
94 
950. Run preflight quality gate: `/preflight` (or follow `.agents/skills/preflight/SKILL.md`)
961. Run linters: `golangci-lint run -v` / `npm run check:all`
972. Run tests: `go test -race -v` / `npm test`
983. Check open PRs to avoid conflicts
994. Format markdown with prettier
1005. Document all exports
101 
102## QA Testing Framework
103 
104The BirdNET-Go QA system lives in `~/src/birdnet-go-qa/`. Always use it instead of ad-hoc test scripts.
105 
106### Key Paths
107 
108| Path | Purpose |
109|------|---------|
110| `~/src/birdnet-go-qa/e2e/tests/` | Playwright E2E test specs |
111| `~/src/birdnet-go-qa/configs/` | Test runtime configs (mounted into containers) |
112| `~/src/birdnet-go-qa/Taskfile.yml` | Task runner for build/deploy/test workflows |
113| `~/src/birdnet-go-qa/Dockerfile.test` | Test container image definition |
114 
115### Running E2E Tests
116 
117```bash
118# Build test image with latest binary
119cp ~/src/birdnet-go/bin/birdnet-go ~/src/birdnet-go-qa/birdnet-go
120cd ~/src/birdnet-go-qa && podman build -t birdnet-go:test -f Dockerfile.test .
121 
122# Deploy test container (dashboard config, port 8085, auth enabled)
123podman run -d --name birdnet-go-test --network host \
124  -v ~/src/birdnet-go-qa/configs/test-runtime-dashboard:/config \
125  birdnet-go:test
126 
127# Run specific test suites
128cd ~/src/birdnet-go-qa/e2e
129npm run test:settings      # Settings CRUD round-trip (15 tests)
130npm run test:fuzz          # Settings fuzzer
131npm run test:integrity     # Config integrity
132npm run test:alerts        # Alert rules
133npm run test:eq-gain       # Audio EQ
134```
135 
136### Config Management Tests
137 
138For config hot-reload QA, these are the relevant test files:
139- `settings-roundtrip.spec.js` - PATCH/PUT persistence, CSRF, validation
140- `settings-fuzzer.spec.js` - Fuzzing settings with random/boundary values
141- `config-integrity.spec.js` - Config structure validation
142- `hot-reload-comprehensive.sh` - Shell-based hot-reload tests
143- `hot-reload-deep.sh` - Deep hot-reload edge cases
144- `audio-eq-save.spec.js` - Audio equalizer save round-trip
145 
146### Forgejo QA Wiki
147 
148Full documentation in the birdnet-go-qa Forgejo wiki: `http://localhost:3000/tphakala/birdnet-go-qa/wiki/`
149 
150## PR Review Workflow
151 
152Automated code review (CodeRabbit, plus the repo's configured review checks) runs on new PRs automatically and checks for bugs, security issues, and best practices. After pushing fixes, you can request a fresh CodeRabbit pass:
153 
154```bash
155# Re-request a CodeRabbit review
156gh pr comment <PR_NUMBER> --body "@coderabbitai review"
157 
158# Or from current branch
159gh pr comment $(gh pr view --json number -q .number) --body "@coderabbitai review"
160```
161 
162### Handling PR Review Comments
163 
164When fetching and addressing code review comments from a PR, use the receiving-code-review skill:
165 
166```text
167/superpowers:receiving-code-review
168```
169 
170This skill ensures:
171 
172- Technical verification before implementing suggestions
173- Appropriate pushback on incorrect feedback
174- No performative agreement - just fix and move on
175- Clarification of unclear items before partial implementation
176