School of Fish

Bluetooth crowd density monitoring system.

Architecture

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  Bluetooth       │────▶│  API Server (Go) │────▶│  TimescaleDB     │
│  Sensors         │POST │  chi router      │     │  + PostGIS       │
└──────────────────┘     └──────┬───────────┘     └──────────────────┘
                                │
                       ┌────────▼─────────┐
                       │  Frontend         │
                       │  Next.js + MapLibre│
                       └──────────────────┘

External Bluetooth sensors detect nearby devices and push detections to the API server via HTTP POST. The server hashes MAC addresses for privacy and bulk-inserts events into TimescaleDB. The frontend visualizes real-time and historical crowd density on a map.

Tech Stack

Layer	Technology
Database	TimescaleDB (PostgreSQL) + PostGIS
Backend	Go, chi, pgx
Frontend	Next.js 15, React, MapLibre GL, Tailwind CSS
Infra	Docker Compose

Quick Start

export INGEST_API_KEY="your-secret-key"
docker compose up

This starts:

• TimescaleDB on port 5432 (with PostGIS, hypertables, and seed data)
• Go API server on port 8080
• Next.js frontend on port 3000

Environment Variables

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
PORT	No	API server port (default: 8080)
INGEST_API_KEY	Yes	Shared secret for sensor authentication

Ingest Endpoint

Bluetooth sensors push device detections to the API server.

POST /api/ingest

Headers

Header	Required	Description
Content-Type	Yes	application/json
X-API-Key	Yes	Shared secret matching INGEST_API_KEY

Request Body

{
  "sensor_id": "550e8400-e29b-41d4-a716-446655440000",
  "devices": [
    {"mac": "AA:BB:CC:DD:EE:FF", "rssi": -65},
    {"mac": "11:22:33:44:55:66", "rssi": -72}
  ]
}

• sensor_id — UUID of the reporting sensor (must exist in sensors table)
• devices — array of detected devices (1–1000 entries)
  • mac — device MAC address (hashed server-side with SHA-256 before storage)
  • rssi — received signal strength indicator

Responses

200 OK

{"ingested": 2}

400 Bad Request

{"error": "invalid request body"}
{"error": "invalid sensor_id"}
{"error": "devices array is required"}
{"error": "too many devices, max 1000"}
{"error": "each device must have mac and rssi"}

401 Unauthorized

{"error": "invalid api key"}

500 Internal Server Error

{"error": "failed to write events"}

Example

curl -X POST http://localhost:8080/api/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{
    "sensor_id": "550e8400-e29b-41d4-a716-446655440000",
    "devices": [
      {"mac": "AA:BB:CC:DD:EE:FF", "rssi": -65},
      {"mac": "11:22:33:44:55:66", "rssi": -72}
    ]
  }'

Privacy

MAC addresses are never stored in plaintext. The server computes a SHA-256 hash of each MAC before inserting into the database.

Development

Backend

cd backend
export DATABASE_URL="postgres://fish:fish@localhost:5432/schooloffish?sslmode=disable"
export INGEST_API_KEY="dev-secret"
go run ./cmd/api

Frontend

cd frontend
npm install
npm run dev

Database

The database is automatically initialized with the schema from db/init.sql on first start. To reset:

docker compose down -v
docker compose up

Project Structure

school-of-fish/
├── docker-compose.yml          # TimescaleDB + Go backend + Next.js frontend
├── README.md
├── backend/
│   ├── cmd/
│   │   └── api/main.go         # API server entry point
│   ├── internal/
│   │   ├── db/                  # Database connection + migrations
│   │   ├── models/              # Go structs matching DB tables
│   │   ├── ingest/              # Bluetooth ingest types + batch writer
│   │   ├── api/                 # HTTP router + handlers
│   │   └── forecast/            # Holt-Winters forecasting
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── app/                 # Next.js App Router pages
│   │   ├── components/          # React components
│   │   └── lib/                 # API client helpers
│   ├── public/
│   │   └── campus.geojson       # Example building polygons
│   └── Dockerfile
└── db/
    └── init.sql                 # Database initialization script