Architecture
GuestNetworks is a unified sensor platform: any vendor sends raw data in, a normalization layer converts it to a canonical format, TimescaleDB stores and rolls it up, and REST + MCP endpoints expose it for queries. This page explains how those pieces connect.
Data flow
Hardware vendor (Meraki / UniFi / Aruba / Square / Density / Verkada / ...)
│
│ HTTP POST /ingest (Bearer token)
▼
Connector normalization layer
│ validates + maps vendor payload → GNCanonicalEvent
│ { venue_id, connector_type, event_type, timestamp,
│ device_hash?, zone_id?, count?, metrics: {...} }
▼
TimescaleDB hypertable (raw events)
│
├── 1-minute rollup ← used for interval ≤ 60 s
├── 1-hour rollup ← used for interval ≤ 1 hr
└── 1-day rollup ← used for interval > 1 hr
│
▼
REST API (GET /api/venues/:id/telemetry?keys=occupancy&...)
MCP tools (get_occupancy, get_environment, get_current_status, ...)
WebSocket stream (/ws — real-time fan-out via Redis pub/sub)Key concepts
The top-level entity — a physical location (hotel, café, retail floor, campus building). Every zone, integration, and event belongs to exactly one venue.
A named sub-area within a venue (e.g. "Main Floor", "Front Entrance", "Bar"). Zones have a type (area | entrance | exit | counter) and an optional capacity. Telemetry and occupancy are aggregated per zone.
An integration between a hardware vendor and GuestNetworks. Each connector has a vendor-specific config schema and translates raw vendor data into GNCanonicalEvents. Currently live: Meraki, UniFi, Aruba, MyWiFi, Square POS, Density, Verkada.
The normalized event format that all connectors emit. Fields: venue_id, connector_type, event_type, timestamp, device_hash (optional), zone_id (optional), count (optional), metrics (object). Canonical events are what gets written to TimescaleDB.
The POST /ingest (and POST /ingest/batch) endpoints accept raw events from connectors and write them through the normalization pipeline. Ingest is authenticated with the same Bearer token as the REST API.
The time-series database that stores all canonical events. Automatic rollups aggregate raw events into 1-minute, 1-hour, and 1-day materialized views. Queries use the smallest aggregate table that covers the requested interval.
The Model Context Protocol endpoint at POST /mcp. LLM agents connect here over Streamable HTTP and call named tools (get_occupancy, get_environment, etc.) that are backed by the same TimescaleDB rollups as the REST API.
Connectors — live vs. roadmap
7 connectors are live in production today. Additional sensor types are on the roadmap. Only live connectors can be attached via the API.
| Connector | Sensor type | Status |
|---|---|---|
| Meraki | WiFi / presence | Live |
| UniFi | WiFi / presence | Live |
| Aruba | WiFi / presence | Live |
| MyWiFi | WiFi / captive portal | Live |
| Square | POS / transactions | Live |
| Density | People counting (IR) | Live |
| Verkada | Video / computer vision | Live |
| HVAC sensors | Environmental (temp/CO₂/humidity) | Roadmap |
| Access control | Entry/exit via badge readers | Roadmap |
API surface
All resource management (venues, zones, integrations, alarms) and analytics queries live under https://api.guestnetworks.com/api/*. Authenticated with Authorization: Bearer. Returns JSON.
API Reference →POST /ingest accepts batches of up to 1,000 canonical events per request. Authenticated with the same Bearer token. 100 requests/min burst cap per operator.
Quickstart →POST /mcp implements the Model Context Protocol (Streamable HTTP). LLM agents call named tools like get_occupancy, get_environment, list_venues. Uses the same Bearer token as REST.
Tool reference →wss://api.guestnetworks.com/ws provides a real-time event push via Redis pub/sub. Auth via ?token= query parameter. Subscribe to venue channels using ThingsBoard-compatible tsSubCmds.
WS reference →