gratheon / telemetry-api 📊

Backend service responsible for logging metrics into timeseries database (influx). Expected to run in the cloud and receive IoT data from beehives.

Main goal and feature is described in Notion

Metrics

• ✅ temperature
  • TODO: add 3d temperature endpoint /metrics/temperature
• ✅ beehive weight (over time)
• ✅ humidity

TODO

• CO2 levels
• atmospheric pressure
• bee traffic (in/out) at the hive entrance
• audio noise volume
• vibrations
• wind speed

URLs

URL	Description
http://telemetry.gratheon.com	Production
http://localhost:8600	Local dev

APIs

This service provides two types of APIs:

GraphQL API

Most flexible and type-safe for web-app, not versioned. Available at /graphql.

Query Operations

• temperatureCelsius(hiveId, timeRangeMin) - Get temperature metrics
• humidityPercent(hiveId, timeRangeMin) - Get humidity metrics
• weightKg(hiveId, timeRangeMin) - Get weight metrics
• weightKgAggregated(hiveId, days, aggregation) - Get aggregated weight data (DAILY_AVG, DAILY_MAX, DAILY_MIN)
• entranceMovementToday(hiveId, boxId) - Get today's bee movement summary
• entranceMovement(hiveId, boxId, timeFrom, timeTo) - Get bee movement history
• populationMetrics(hiveId, days) - Get population metrics (bee count, drone count, varroa mites)

Mutation Operations

• addMetric(hiveId, fields) - Add IoT sensor metrics (temperature, humidity, weight)
• addPopulationMetric(hiveId, fields, inspectionId, timestamp) - Add population data

See schema.graphql for full API specification.

REST API

Legacy API intended for IoT devices, versioned. Available at /iot/v1/metrics.

POST /iot/v1/metrics

• Accepts single metric or array of metrics
• Requires Bearer token authentication
• Supports batch operations (up to 1000 metrics per request)

Example:

{
  "hiveId": "123",
  "timestamp": 1234567890,
  "fields": {
    "temperatureCelsius": 25.5,
    "humidityPercent": 65.0,
    "weightKg": 45.2
  }
}

Database Schema

The service uses PostgreSQL with three main tables:

beehive_metrics

Stores IoT sensor data (temperature, humidity, weight)

- id (INT, auto increment)
- hive_id (VARCHAR(50))
- temperature_celsius (FLOAT)
- humidity_percent (FLOAT)
- weight_kg (FLOAT)
- time (TIMESTAMP)

entrance_observer

Stores bee entrance movement data from video processing

- id (INT, auto increment)
- hive_id (VARCHAR(50))
- box_id (VARCHAR(50))
- bees_out (FLOAT)
- bees_in (FLOAT)
- net_flow (FLOAT)
- avg_speed_px_per_frame (FLOAT)
- p95_speed_px_per_frame (FLOAT)
- stationary_bees_count (INT)
- detected_bees (INT)
- bee_interactions (INT)
- time (TIMESTAMP)

population_metrics

Stores manual inspection data about hive population

- id (INT, auto increment)
- hive_id (VARCHAR(50))
- inspection_id (VARCHAR(50))
- bee_count (INT)
- drone_count (INT)
- varroa_mite_count (INT)
- time (TIMESTAMP)

See migrations/ for full schema definitions.

Testing

This project uses Go tests for both unit-style and integration-style coverage.

Running Tests

# Run all Go tests
go test ./...

# Run tests in Docker (includes all dependencies)
docker compose -f docker-compose.test.yml up --build --abort-on-container-exit

# Start test environment for manual testing
docker compose -f docker-compose.test.yml up -d

# Stop test environment
docker compose -f docker-compose.test.yml down -v

Test Coverage

Go tests cover:

• REST request validation and success paths
• GraphQL query and mutation validation
• Resolver and controller behavior
• Prometheus metrics wiring
• Optional Postgres roundtrip testing against Dockerized PostgreSQL

Tests include:

• Input validation and error cases
• REST and GraphQL contract checks
• Time range queries and aggregations
• Database migration and storage roundtrip coverage

Installation & Development

Start telemetry API:

just start

Or run locally without Docker:

just run

Architecture

We are NOT using timeseries DB (influx, clickhouse) because we don't have manpower to maintain multiple storage engines at this time. So we're relying on PostgreSQL for ease of management, even though its not as efficient.

flowchart LR
	hardware-beehive-sensors[<a href="https://github.com/Gratheon/hardware-beehive-sensors">hardware-beehive-sensors</a>] -."send aggregate (5sec)\n metric value".-> telemetry-api

	telemetry-api --"update beehive entrance daily traffic counters"--> postgres[(<a href="https://github.com/Gratheon/postgres">postgres</a>)]
	beehive-entrance-video-processor[<a href="https://github.com/Gratheon/beehive-entrance-video-processor">beehive-entrance-video-processor</a>] -."send entrance\n traffic metric".-> telemetry-api
	telemetry-api --"store bee traffic timeseries" --> postgres
	grafana[(<a href="https://github.com/Gratheon/grafana">grafana</a>)] --"fetch history"--> postgres

	telemetry-api --"verify API tokens for REST calls"--> user-cycle[<a href="https://github.com/Gratheon/user-cycle">user-cycle</a>]
	web-app[<a href="https://github.com/Gratheon/web-app">web-app</a>] --"display advanced configureable graphs"--> grafana
	web-app --"query for simplistic metrics\nPOST graphql"-->graphql-router[<a href="https://github.com/Gratheon/graphql-router">graphql-router</a>]--> telemetry-api

Loading

License

This project is dual-licensed:

• AGPL v3 - For open source use:

  • ✅ You can use, modify, and distribute the software
  • ✅ Source code is freely available
  • ⚠️ If you modify and host a public instance, you must share your modifications
  • ⚠️ Any derivative work must also be licensed under AGPL v3

• Commercial License - For enterprise customers who need:

  • 🏢 On-premise deployment without source disclosure
  • 🔧 Custom modifications without copyleft obligations
  • 📞 Priority support and SLA guarantees