From fa345208eb08d554973509eeb1cd6470057bb67b Mon Sep 17 00:00:00 2001 From: "Enot (ded) Skelly" Date: Fri, 5 Jun 2026 15:57:14 -0700 Subject: [PATCH] update readme --- README.md | 77 ++++++++++++++++++++++--------------------------------- 1 file changed, 31 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 186b476..c9d04c4 100644 --- a/README.md +++ b/README.md @@ -44,41 +44,18 @@ For deployment instructions including the frontend app, see the deployment docs. ``` beacon-server/ -├── cmd/beacon/ entry point -├── db/ -│ ├── migrations/ SQL schema (001_schema.sql) +├── cmd/beacon/ entry point +├── db/ store implementations and sqlc generated code +│ ├── migrations/ SQL schema │ ├── queries/ sqlc query definitions -│ ├── sqlc/ generated Go DB code (do not edit) -│ ├── store.go Store type, shared helpers -│ ├── packets.go packet and observation store methods -│ ├── nodes.go node store methods -│ ├── observers.go observer store methods -│ ├── channels.go channel and message store methods -│ ├── stats.go stats and materialized view methods -│ ├── config.go IATA and region store methods -│ └── scopes.go transport scope store methods +│ └── sqlc/ generated Go DB code (do not edit) ├── internal/ -│ ├── api/ -│ │ ├── handlers/ HTTP route handlers -│ │ ├── middleware/ Auth middleware stub -│ │ ├── router/ Chi router wiring -│ │ ├── reader.go Reader interface and Page type -│ │ ├── packets.go packet response types and helpers -│ │ ├── nodes.go node response types and helpers -│ │ ├── observers.go observer response types -│ │ ├── channels.go channel and message response types -│ │ ├── stats.go stats response types -│ │ ├── iata.go IATA response type -│ │ └── regions.go region response types +│ ├── api/ REST API types, Reader interface, route handlers +│ │ └── handlers/ HTTP route handlers │ ├── config/ config file loading and DB seeding │ ├── hub/ WebSocket fan-out broker -│ ├── ingest/ -│ │ ├── ingest.go Worker, DB interface, MQTT connection -│ │ ├── packet.go packet pipeline, payload parsing -│ │ ├── status.go status message handling -│ │ ├── side_effects.go payload-type side effects (node upsert, channel messages) -│ │ └── capability.go firmware capability detection │ ├── iatadb/ static IATA → country/continent map (generated) +│ ├── ingest/ MQTT ingest pipeline │ ├── keystore/ channel key store │ ├── scopestore/ transport scope key store │ └── ws/ WebSocket handler and IP limiter @@ -329,29 +306,37 @@ GET /api/v1/packets?iata=YOW&afterId=12345&limit=100 | Method | Path | Description | | ------ | ----------------------------------- | -------------------------------------------------------------------------------------------------- | | `GET` | `/brokers` | List MQTT brokers and connection status | -| `GET` | `/iatas` | List all known IATA codes | -| `GET` | `/iatas/{iata}` | Get a single IATA code | -| `GET` | `/regions` | List all regions (summary) | -| `GET` | `/regions/{id}` | Get a single region with IATA list | | `GET` | `/channels` | List channels (optional: `?hash=&iata=&limit=50`) | | `GET` | `/channels/{id}` | Get channel detail by integer ID | | `GET` | `/channels/{id}/messages` | List messages for a channel (optional: `?since=&iata=&limit=50`) | +| `GET` | `/iatas` | List all known IATA codes | +| `GET` | `/iatas/{iata}` | Get a single IATA code | | `GET` | `/messages` | List all messages (optional: `?channelId=&channelHash=&iata=&since=&limit=50`) | -| `GET` | `/observers` | List observers (optional: `?iata=&type=&broker=&status=online\|offline`) | -| `GET` | `/observers/{observerId}` | Get observer detail including broker last-seen timestamps | -| `GET` | `/observers/{observerId}/telemetry` | Observer telemetry history | -| `GET` | `/observers/{observerId}/adverts` | Adverts heard by observer | -| `GET` | `/packets` | List packets with filters | -| `GET` | `/packets/{packetHash}` | Get packet with all observations | +| `GET` | `/messages/backfill` | Backfill messages after a given message ID | | `GET` | `/nodes` | List nodes | | `GET` | `/nodes/{nodeId}` | Get node detail | | `GET` | `/nodes/{nodeId}/observations` | List observations for a node | -| `GET` | `/stats/overview` | Network overview stats | +| `GET` | `/observers` | List observers (optional: `?iata=&type=&broker=&status=online\|offline`) | +| `GET` | `/observers/{observerId}` | Get observer detail including broker last-seen timestamps | +| `GET` | `/observers/{observerId}/adverts` | Adverts heard by observer | +| `GET` | `/observers/{observerId}/telemetry` | Observer telemetry history | +| `GET` | `/packets` | List packets with filters | +| `GET` | `/packets/backfill` | Backfill packets after a given observation ID | +| `GET` | `/packets/{packetHash}` | Get packet with all observations | +| `GET` | `/regions` | List all regions (summary) | +| `GET` | `/regions/{id}` | Get a single region with IATA list | +| `GET` | `/routes` | List known routes (all hops high confidence) | +| `GET` | `/routes/search` | Search routes by source and destination hash | +| `GET` | `/scopes` | List transport scopes | +| `GET` | `/scopes/{name}` | Get scope detail | | `GET` | `/stats/observations` | Hourly observation time series (last 7 days by default) | +| `GET` | `/stats/overview` | Network overview stats | | `GET` | `/stats/payload-breakdown` | Observation counts by payload type (last 24h by default) | +| `GET` | `/stats/scopes` | Configured region scopes and breakdown of packets, nodes, observers | | `GET` | `/stats/top-nodes` | Top N nodes by observation count (from materialized view) | | `GET` | `/stats/top-observers` | Top N observers by observation count (last 24h by default) | -| `GET` | `/stats/scopes` | Configured region scopes and breakdown of packets, nodes, observers | +| `GET` | `/traces` | List trace tags with filters | +| `GET` | `/traces/{tag}` | Get full trace detail with resolved routes | --- @@ -472,10 +457,10 @@ AIRPORTS_CSV=/path/to/airports.csv go run ./internal/iatadb/gen details - [x] Propagation time calculation - [x] Trace route resolution via path hashes (resolvedRoute on packet detail) - -### In progress / next - -- [ ] Dedicated routes and traces endpoints (see issue #32) +- [x] Trace packets: trace tag storage, list and detail endpoints with resolved + routes +- [x] Known routes: fully resolved paths stored at ingest, list and search + endpoints ### Future