# AGENTS.md

Project-level instructions for working in this repository. Read this before
touching the filesystem.

## What this is

Go helper packages for talking to a [Wingbits](https://wingbits.com) ADS-B
station (e.g. the MGW310) and decoding the readsb / tar1090 JSON files it serves.

Module: `gitea.libretechconsulting.com/rmcguire/wingbits` (Go 1.26).

## Layout

```
pkg/types/readsb     # decode types for aircraft/receiver/stats/outline + aircraft filters
pkg/types/wingbits   # decode types for diagnostics/metrics/status (+ Prometheus text parser)
pkg/client           # HTTP Client: query + stream every endpoint, returns the types above
cmd/wingbits         # flag-driven CLI for one-off queries (test/utility tool)
```

Rules of the split:

- `pkg/types/*` is **decode-only**. No HTTP, no I/O beyond `encoding/json` and the
  Prometheus text parser. These packages must not import `pkg/client`.
- `pkg/client` owns all transport/request logic and depends on both type packages.
- Keep the two type packages independent of each other.

## Station topology (important for endpoint routing)

A station exposes two HTTP roots; both are plaintext HTTP on the test unit:

| Root      | Default port | Serves                                                        |
|-----------|--------------|---------------------------------------------------------------|
| Wingbits  | `:8088`      | `/network/diagnostics`, `/metrics`, `/tailscale/status`, and readsb files under `/readsb/` |
| tar1090   | `:8504`      | readsb files under `/data/`, plus `/data/outline.json`        |

`outline.json` is **only** served by the tar1090 root. When a tar1090 endpoint is
configured it overrides the Wingbits root for all readsb files.

## Testing

```
go test ./...
```

Tests decode captured fixtures in each package's `testdata/` directory and drive
the client against an `httptest` server. `pkg/client` reuses the fixtures from
`pkg/types/*/testdata` (a single source of truth — do not duplicate them).

The live reference unit is an **MGW310 at `192.168.0.127`** (also
`miner.mcguire.local`), plaintext HTTP on all ports. Re-capture fixtures from it
with `curl` when fields change; never hand-edit `testdata/` payloads.

## Coding standards

- Go only. Keep functions within ~25 lines; decompose helpers as needed.
- Every package has a package comment (Go convention) in one of its files.
- Comment only the non-obvious. Field docs on the decode structs are intentional
  — they capture readsb/Wingbits semantics that aren't evident from the name.
- The known JSON quirks to preserve when editing decode types:
  - `alt_baro` may be the string `"ground"` instead of a number → `readsb.AltBaro`.
  - readsb timestamps are fractional-second Unix floats → `readsb.UnixTime`.
  - `outline.json` points are `[lat, lon, altFeet]` tuples → `readsb.RangePoint`.