CLAUDE.md

1# API v2 Development Guidelines
2 
3## Essential Reference
4 
5**ALWAYS read `internal/api/v2/README.md` first** - it is the endpoint catalog:
6 
7- Complete list of all API endpoints, grouped by domain
8- Per-route authentication requirements
9- Request/response shapes and best practices
10 
11## Architecture (post-split)
12 
13`internal/api/v2` is a thin composition root (package `api`) plus one subpackage
14per domain. The dependency direction is strictly acyclic:
15 
16```
17internal/api (parent server.go)
18        |  api.New, *api.Controller
19        v
20internal/api/v2            package api  (the facade)
21  Controller{ *apicore.Core; <domain>.Handler fields }
22  New / NewWithOptions / InitializeAPI, ordered initRoutes()
23        |                         |                      |
24        | imports                 | imports              | imports
25        v                         v                      v
26internal/api/v2/analytics   internal/api/v2/weather  ...  internal/api/v2/<domain>
27        |  type Handler struct{ *apicore.Core }; New; RegisterRoutes
28        +------------------+------------------+
29                 | imports          | imports
30                 v                  v
31       internal/api/v2/apicore   internal/api/v2/dto
32       (Core: shared state,        (cross-domain request/
33        helpers, middleware,        response DTOs)
34        SSE hub, broadcasters)
35                 |
36                 v
37   leaf pkgs: conf, datastore, logger, securefs, observability, ...
38```
39 
40Rule, stated once: **domains depend on `apicore` and `dto`; the facade depends on
41`apicore` and every domain; `apicore` depends on neither a domain nor the
42facade.** There is no path back up, so no import cycle is possible. This is
43enforced mechanically by `internal/api/v2/apicore/import_guard_test.go` (a
44`go list -deps` check that fails if `apicore` or `apitest` ever imports a domain
45or the facade); it runs inside the normal `go test ./...` unit-test jobs.
46 
47### What lives where
48 
49- **`apicore`** (`internal/api/v2/apicore`): the shared `Core` struct (deps,
50  settings accessors, error/log helpers, telemetry reporting, `RequireDatastore`),
51  the shared group middleware (`TunnelDetectionMiddleware`, `LoggingMiddleware`,
52  `PrivateModeAuth`, the trusted-proxy IP extractor, `GetAuthMiddleware`), the SSE
53  hub (`SSEManager`, `SSEClient`) and the broadcasters (`BroadcastDetection`,
54  `BroadcastSoundLevel`, `BroadcastPending`). Everything a domain handler touches
55  is **exported** on `Core` (cross-package field/method promotion does not bypass
56  Go's export rules).
57- **`<domain>`** (e.g. `internal/api/v2/weather`): `type Handler struct{ *apicore.Core }`,
58  `New(core *apicore.Core) *Handler`, and `RegisterRoutes(g *echo.Group)`. The
59  handler embeds `*apicore.Core` **by pointer** so the shared members promote onto
60  it. Domain-only types and helpers stay unexported in the domain package.
61- **`dto`** (`internal/api/v2/dto`): request/response structs shared by 2+ domains
62  (e.g. `SourceInfo`, `WeatherInfo`, `RangeFilterSpecies`). Domain-only structs
63  stay in their domain package.
64- **`apitest`** (`internal/api/v2/apitest`): importable test scaffolding built
65  around `*apicore.Core`. Domain tests build their own handler:
66  `h := weather.New(apitest.NewCore(t))`. `apitest` imports only `apicore`/`dto`.
67- **`api` (facade, directory root)**: `Controller` embeds `*apicore.Core` and holds
68  one field per domain Handler. `New`/`NewWithOptions`/`InitializeAPI` build the
69  single `Core`, construct each domain Handler around it, and `initRoutes` calls
70  every `RegisterRoutes` in a deterministic ordered list. `settings.go` (and its
71  large test suite) intentionally still lives here, as does the facade-owned
72  name-map plumbing (`name_maps.go`) and the cross-domain `/system` wiring
73  (`system_routes.go`).
74 
75> **Embed `*apicore.Core` by pointer only, never by value.** `Core` holds
76> `atomic.Pointer`, `sync.RWMutex` and `sync.WaitGroup` fields; copying it by value
77> desyncs the atomics and trips `go vet` copylocks. A single `Core` is built once
78> in `NewWithOptions` and shared by pointer to every handler and the facade.
79 
80> **Broadcaster-payload rule.** Because the SSE broadcasters live in `apicore` and
81> are called from domains, their parameter/return types must stay in leaf packages,
82> `dto`, or `apicore` itself - **never a domain type** - or `apicore` would have to
83> import a domain and close a cycle. Use a leaf type, `any` + serialize, or push the
84> payload struct to `dto`.
85 
86## Adding endpoints
87 
88### Recipe A - new endpoint in an EXISTING domain (no facade change)
89 
901. Add the handler method on that domain's `*Handler` in
91   `internal/api/v2/<domain>/`, receiver named `c`:
92 
93```go
94   func (c *Handler) GetThing(ctx echo.Context) error {
95       if c.DS == nil {
96           return c.HandleError(ctx, nil, "datastore unavailable", http.StatusServiceUnavailable)
97       }
98       // ... use c.CurrentSettings(), c.HandleError(...), dto.Thing, etc.
99       return ctx.JSON(http.StatusOK, resp)
100   }
101```
102 
1032. Add the route line to that domain's `RegisterRoutes(g *echo.Group)`:
104 
105```go
106   g.GET("/things", c.GetThing)                       // public
107   g.POST("/things", c.CreateThing, c.AuthMiddleware) // protected
108```
109 
1103. Update `README.md` with the new endpoint. No facade edit is needed.
111 
112### Recipe B - new domain
113 
1141. Create `internal/api/v2/<domain>/<domain>.go` with
115   `type Handler struct{ *apicore.Core }`, `New(core *apicore.Core) *Handler`, and
116   `RegisterRoutes(g *echo.Group)`.
1172. In the facade (`api.go`): add one `*<domain>.Handler` field to `Controller`, one
118   `c.<domain> = <domain>.New(c.Core)` line in `NewWithOptions`, and one ordered
119   entry `{"<domain> routes", func() { c.<domain>.RegisterRoutes(c.Group) }}` in
120   `initRoutes`. Registration is explicit (not `init()`-based) so order stays
121   deterministic; preserve the existing ordering.
1223. New domains are subpackages of `api/v2`, so the "all new endpoints stay under
123   api/v2" rule holds.
124 
125A single `RegisterRoutes` is the norm, but a larger domain may expose several named
126registrars (e.g. `detections` has `RegisterSearchRoutes` + `RegisterDetectionRoutes`;
127`analytics` has `RegisterAnalyticsRoutes` + `RegisterHeatmapRoutes` +
128`RegisterInsightsRoutes` + `RegisterDatabaseOverviewRoutes`; `audio` and `system`
129similarly). Each is wired as its own ordered `initRoutes` entry, which keeps the
130original per-route registration order across the split.
131 
132### Recipe C - new shared dependency or middleware
133 
134- Shared dependency: add an exported field (+ functional option) on `apicore.Core`
135  and thread it through `NewCore`; domains read it via promotion.
136- Shared middleware: add it on `apicore` and apply it at the facade group level in
137  `NewWithOptions` (preserving order), or as a shared per-route middleware
138  constructor that domains call.
139 
140## Authentication patterns
141 
142- Public endpoints: no middleware.
143- Protected endpoints/groups: apply the promoted `c.AuthMiddleware` field directly,
144  e.g. `g.Group("/control", c.AuthMiddleware)` or
145  `g.POST("/path", c.Handler, c.AuthMiddleware)`. (`c.GetAuthMiddleware()` returns
146  the same value for callers that prefer an accessor.) The middleware is injected
147  from the parent server via the `WithAuthMiddleware` functional option.
148- Rate-limited streams: `middleware.RateLimiterWithConfig(config)`.
149- PrivateMode: all endpoints are gated by `apicore.PrivateModeAuth` group
150  middleware; the bootstrap/login/live-audio carve-outs are listed in the facade's
151  `isPrivateModeExempt` allow-list (keyed on method + path, fail-closed).
152 
153## Route namespace guide
154 
155The API uses distinct namespaces. Adding endpoints to the wrong namespace causes
156route collisions.
157 
158| Namespace | Purpose | Registration | Example |
159|---|---|---|---|
160| `/audio/:id` | Detection audio clips by numeric note ID | `c.Echo.GET(...)` (media domain) | `ServeAudioByID` |
161| `/system/audio/*` | Audio device/source management (protected) | `protectedGroup.Group("/audio")` (audio domain) | `GetAudioDevices`, `ListAudioSources` |
162| `/streams/*` | Live streaming, SSE, source listing (public) | `g.GET("/streams/...")` (audio/sse domains) | `StreamAudioLevel`, `ListStreamSources` |
163| `/media/*` | Static media files (images, spectrograms) | `g.GET("/media/...")` (media domain) | `ServeSpectrogram` |
164 
165**WARNING:** `GET /api/v2/audio/:id` is registered directly on `c.Echo` (not the
166`/api/v2` group) and catches ALL paths under `/api/v2/audio/*`. Any non-numeric
167path like `/api/v2/audio/sources` returns 400. Never add new endpoints under
168`/api/v2/audio/` unless they use a numeric `:id` parameter.
169 
170**Public endpoints that expose source metadata** must anonymize display names for
171unauthenticated clients (the audio domain does this with its local
172`getAnonymizedSourceName`, matching `StreamAudioLevel`).
173 
174## Critical rules
175 
176- **Never duplicate existing endpoints** - check `README.md` first.
177- **Always validate input** - prevent injection attacks; use SecureFS (`c.SFS`) for
178  file operations and parameterized queries only.
179- **Use structured logging** - `c.LogAPIRequest(ctx, level, msg, args...)` and the
180  `c.LogInfoIfEnabled`/`LogWarnIfEnabled`/`LogErrorIfEnabled`/`LogDebugIfEnabled`
181  family.
182- **Follow the error format** - `return c.HandleError(ctx, err, "message", statusCode)`
183  (or `c.HandleErrorWithKey(...)` for an i18n key). The `ErrorResponse` shape and
184  correlation-id behavior live in `apicore`.
185- **Hot-reload** - read settings per request via `c.CurrentSettings()` /
186  `c.ControllerSettings()` (the atomic snapshot on `Core`); never branch on settings
187  captured at startup.
188- **Document in README.md** - update the endpoint table immediately.
189 
190## Future api/v3
191 
192A future `internal/api/v3` lives as a sibling facade with its own `Core` (do not
193re-monolith). It can reuse these patterns but should not couple to `apicore` so the
194two versions evolve independently.
195 
196## CSRF Protection (legacy info)
197 
198CSRF middleware validates tokens from the `X-CSRF-Token` header (primary) or the
199`_csrf` form field (fallback); it is wired globally in the parent `server.go`. The
200token is issued by the `/app/config` endpoint via `middleware.EnsureCSRFToken()`.
201Public read-only endpoints skip CSRF validation.
202