CLAUDE.md

1# Internal/Errors Package Guidelines
2 
3## Critical Rules
4 
5### Import ONLY This Package
6 
7```go
8// ✅ CORRECT
9import "github.com/tphakala/birdnet-go/internal/errors"
10 
11// ❌ DO NOT import standard errors, unless it is to avoid circular dependency
12import "errors"  // FORBIDDEN
13```
14 
15## Component Registration
16 
17### Required: Register in init() (errors.go:334-348)
18 
19```go
20func init() {
21    RegisterComponent("packagename", "display-name")
22}
23```
24 
25### Current Components
26 
27- birdnet, myaudio, datastore, imageprovider
28- diskmanager, mqtt, weather, conf, telemetry
29- birdweather, backup
30 
31⚠️ **Unregistered components cause incorrect telemetry tagging**
32 
33## Quick Patterns
34 
35### Basic Error
36 
37```go
38err := errors.New(originalErr).
39    Component("datastore").
40    Category(errors.CategoryDatabase).
41    Context("operation", "save_detection").
42    Build()
43```
44 
45### Descriptive Error (Preferred)
46 
47```go
48err := errors.Newf("Wikipedia API missing 'query.pages' structure").
49    Component("imageprovider").
50    Category(errors.CategoryImageFetch).
51    Context("operation", "parse_pages_from_response").
52    Context("expected_path", "query.pages").
53    Build()
54```
55 
56### Validation Error
57 
58```go
59err := errors.Newf("scientific name cannot be empty").
60    Component("imageprovider").
61    Category(errors.CategoryValidation).
62    Build()
63```
64 
65## Categories (errors.go:23-50)
66 
67- **Critical**: CategoryModelInit, CategoryModelLoad, CategoryConfiguration
68- **Data**: CategoryDatabase, CategoryFileIO, CategoryFileParsing
69- **Network**: CategoryNetwork, CategoryHTTP, CategoryRTSP
70- **Service**: CategoryImageFetch, CategoryMQTTConnection, CategoryWeather
71- **System**: CategoryDiskUsage, CategorySystem, CategoryProcessing
72 
73## Troubleshooting
74 
75### Wrong Component in Telemetry?
76 
771. Check component is registered in init()
782. Always use `.Component()` explicitly
793. See README.md:436-465
80 
81### Generic Sentry Titles?
82 
83- Add `Context("operation", "specific_action")`
84- Use descriptive messages with `errors.Newf()`
85- See README.md:427-434
86 
87### Performance Concerns?
88 
89- Event bus handles async (2.5ns overhead when disabled)
90- See README.md:569-574
91 
92## Full Documentation
93 
94For comprehensive details: `internal/errors/README.md`
95 
96- Import guidelines: lines 16-32
97- Context best practices: lines 163-191
98- Component registration: lines 195-265
99- Common patterns: lines 283-362
100