RunSight Backend

RunSight Backend is a REST API service for the RunSight smart running system. It manages user authentication, device pairing, and run data for IoT devices (smart glasses) and mobile applications.

System Overview

RunSight is an autonomous IoT-first running assistance system where smart glasses provide real-time AI guidance to runners. The backend serves as the central data hub that:

• Manages secure device pairing between mobile apps and IoT devices
• Stores running sessions with AI metrics (obstacle detection, lane keeping, warnings)
• Provides offline-first sync capabilities for IoT devices
• Delivers personalized statistics and run history to mobile users

Core Principles:

• IoT devices are autonomous (runs happen without mobile connectivity)
• Mobile apps are view-only (read history, manage devices)
• Backend is stateless with optional real-time features
• Offline-first with automatic sync when network is available

Features

• Secure Authentication – JWT-based user auth and device token management
• Device Pairing – 6-digit code pairing system for mobile-IoT connection
• Run Data Management – Upload, store, and sync running sessions with AI metrics
• Statistics & Analytics – Aggregated performance insights and history
• Monitoring & Health – Health checks and structured logging

Quick Start

git clone https://github.com/labmino/runsight-backend.git
cd runsight-backend

# Using Docker (recommended)
docker-compose up -d

# Or manual setup
cp .env.example .env
go run cmd/server/main.go

Server runs on http://localhost:8080 with PostgreSQL database.

API Endpoints

Base URL: http://localhost:8080/api/v1

Authentication

• Mobile apps: Authorization: Bearer <jwt_token>
• IoT devices: Authorization: Bearer <device_token>

Monitoring & Health

• GET /health - Basic health check
• GET /health/detailed - Detailed health with system metrics
• GET /ready - Readiness probe (checks database connectivity)
• GET /live - Liveness probe
• GET /metrics - Application metrics (users, devices, runs, system stats)

Authentication & User Management

• POST /auth/register - User registration
• POST /auth/login - User authentication
• GET /auth/profile - Get user profile (requires auth)
• PUT /auth/profile - Update user profile (requires auth)

Mobile App Endpoints (requires JWT auth)

Device Pairing

• POST /mobile/pairing/request - Request pairing code for device
• GET /mobile/pairing/:session_id/status - Check pairing status

Device Management

• GET /mobile/devices - List paired devices
• DELETE /mobile/devices/:device_id - Remove/unpair device

Run Data & Analytics

• GET /mobile/runs - List runs with pagination and date filtering
• GET /mobile/runs/:run_id - Get detailed run information
• GET /mobile/runs/:run_id/waypoints - Get run route/waypoint data
• PATCH /mobile/runs/:run_id - Update run title/notes
• GET /mobile/stats - Get aggregated user statistics

IoT Device Endpoints

Device Pairing

• POST /iot/pairing/verify - Verify pairing code and register device

Data Upload (requires device token auth)

• POST /iot/runs/upload - Upload single run with AI metrics
• POST /iot/runs/batch - Batch upload multiple runs
• POST /iot/devices/status - Update device status (battery, firmware)
• GET /iot/devices/config - Get device configuration

Development

Project Structure:

cmd/server/main.go          # Entry point
internal/
├── handlers/               # HTTP handlers (auth, mobile, iot, monitoring)
├── models/                 # Database models (user, device, run, ai_metrics)
├── services/               # Business logic (pairing)
├── middleware/             # Auth, rate limiting, security
├── database/               # PostgreSQL connection and migrations
└── utils/                  # JWT, logging, responses, error codes
tests/                      # Unit and integration tests

Run locally:

go run cmd/server/main.go

Run tests:

go test ./...

Deployment

Docker (recommended):

docker-compose up -d

Production:

go build -o server cmd/server/main.go
GIN_MODE=release ./server

License

MIT License - see LICENSE file.