IoT Platform - POC/Demo

A complete multi-tenant IoT platform demonstrating data collection from edge devices via MQTT, cloud processing, storage, and visualization.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                       Cloud (VM)                             │
│  ┌──────────┐   ┌────────┐   ┌──────────┐   ┌──────────┐  │
│  │ Nginx    │──▶│ Go API │──▶│PostgreSQL│   │ Grafana  │  │
│  │ (Proxy)  │   │  Core  │   │          │◀──│          │  │
│  └──────────┘   └────────┘   └──────────┘   └──────────┘  │
│       │              ▲                                       │
│       │              │                                       │
│       ▼              │                                       │
│  ┌──────────┐   ┌────────────┐                             │
│  │Dashboard │   │MQTT Broker │                             │
│  │ (Node.js)│   │  (Cloud)   │                             │
│  └──────────┘   └────────────┘                             │
│                       ▲                                      │
└───────────────────────┼──────────────────────────────────────┘
                        │
                   MQTT Bridge
                        │
┌───────────────────────┼──────────────────────────────────────┐
│                  Client Site (Raspberry Pi)                  │
│                       ▼                                      │
│  ┌────────────┐   ┌──────────┐                             │
│  │ MQTT Local │◀──│ IoT      │                             │
│  │  Broker    │   │ Devices  │                             │
│  └────────────┘   └──────────┘                             │
│       ▲                                                      │
│       │                                                      │
│  ┌────────────┐                                             │
│  │Mock MQTT   │  (For testing - can be disabled)           │
│  │ Publisher  │                                             │
│  └────────────┘                                             │
└─────────────────────────────────────────────────────────────┘

Features

Multi-tenant Architecture: Full tenant separation with hierarchical data model
MQTT Topic Structure: projects/{customer}/{department}/{device}/{metric}
Real-time Data Streaming: MQTT-based data ingestion
REST API: Comprehensive API for data access
Web Dashboard: Node.js MVC dashboard for data visualization
Grafana Integration: Advanced analytics and visualization
Mock Data Generator: Test data generation when real devices aren't available
Edge Simulation: Local MQTT broker simulating Raspberry Pi edge device
Containerized: All services run in Docker containers

Components

Cloud Services

PostgreSQL: Multi-tenant database with hierarchical data model
MQTT Cloud Broker (Mosquitto): Cloud MQTT broker for device communication
Go API/Core:
- Subscribes to MQTT topics
- Processes and stores metrics in PostgreSQL
- Provides REST API endpoints
Node.js Dashboard: Web UI for viewing devices and metrics
Grafana: Advanced visualization and analytics
Nginx: Reverse proxy routing requests to appropriate services

Edge Services (Simulated)

MQTT Local Broker: Edge broker (simulates Raspberry Pi)
MQTT Bridge: Forwards messages from local to cloud broker
Mock Publisher: Generates test data (can be disabled for real devices)

Quick Start

Prerequisites

Docker and Docker Compose installed
Ports available: 80, 1883, 1884, 3000, 3001, 5432, 8080, 9001

Running the Platform

Clone the repository

git clone <repository-url>
cd mqtt-dashboard

Start all services
```
docker compose up -d
```
Check service status
```
docker compose ps
```

View logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f api-core
docker compose logs -f mqtt-publisher

Accessing the Services

Dashboard: http://localhost (via Nginx) or http://localhost:3000 (direct)
API: http://localhost:8080 or http://localhost/api
Grafana: http://localhost:3001 (login: admin/admin)
MQTT Cloud Broker: localhost:1883
MQTT Local Broker: localhost:1884

Using Real Devices

To switch from mock data to real IoT devices:

Disable the mock publisher:

docker compose stop mqtt-publisher

Or set in docker-compose.yml:

mqtt-publisher:
  environment:
    ENABLE_PUBLISHER: "false"

Connect your devices to the MQTT local broker:
- Host: localhost (or your server IP)
- Port: 1884
- Topic format: projects/{customer}/{department}/{device}/{metric}
- Payload format (JSON):
```
{
  "value": 23.5,
  "timestamp": "2024-01-01T12:00:00Z",
  "device": "sensor-001",
  "metric": "temperature",
  "unit": "celsius"
}
```

Test with mosquitto_pub:

docker exec mqtt-local mosquitto_pub \
  -t "projects/my-factory/production/sensor-001/temperature" \
  -m '{"value":25.3,"timestamp":"2024-01-01T12:00:00Z","device":"sensor-001","metric":"temperature","unit":"celsius"}'

API Endpoints

Statistics

GET /api/v1/stats/overview - System overview statistics

Tenants

GET /api/v1/tenants - List all tenants
GET /api/v1/tenants/{tenant_code} - Get tenant details

Customers

GET /api/v1/tenants/{tenant_code}/customers - List customers for tenant

Departments

GET /api/v1/customers/{customer_code}/departments - List departments

Devices

GET /api/v1/departments/{department_code}/devices - List devices
GET /api/v1/devices/{device_code} - Get device details

Metrics

GET /api/v1/metrics/latest?limit=100 - Get latest metrics across all devices
GET /api/v1/devices/{device_code}/metrics?limit=100 - Get device metrics
GET /api/v1/metrics/search?customer=X&device=Y - Search metrics with filters

Database Schema

Hierarchy

Tenants
  └─ Customers
      └─ Departments
          └─ Devices
              └─ Metrics

Main Tables

tenants - Tenant organizations
customers - Customer sites (belongs to tenant)
departments - Departments within customer sites
devices - IoT devices
metrics - Time-series sensor data

Environment Variables

API Core

DB_HOST - PostgreSQL host (default: postgres)
DB_PORT - PostgreSQL port (default: 5432)
DB_USER - Database user
DB_PASSWORD - Database password
DB_NAME - Database name
MQTT_BROKER - MQTT broker host (default: mqtt-cloud)
MQTT_PORT - MQTT broker port (default: 1883)
API_PORT - API server port (default: 8080)

Mock Publisher

MQTT_BROKER - MQTT broker host (default: mqtt-local)
MQTT_PORT - MQTT port (default: 1883)
PUBLISH_INTERVAL - Publish interval in seconds (default: 5)
ENABLE_PUBLISHER - Enable/disable publisher (default: true)

MQTT Bridge

LOCAL_BROKER - Local broker address (default: mqtt-local:1883)
CLOUD_BROKER - Cloud broker address (default: mqtt-cloud:1883)

Development

Rebuilding Services

# Rebuild all services
docker-compose up -d --build

# Rebuild specific service
docker-compose up -d --build api-core

Viewing Service Logs

# Follow all logs
docker-compose logs -f

# Follow specific service
docker-compose logs -f mqtt-publisher
docker-compose logs -f api-core

Database Access

# Access PostgreSQL
docker exec -it mqtt-postgres psql -U iot_user -d iot_platform

# Example queries
SELECT * FROM tenants;
SELECT * FROM v_metrics_hierarchy ORDER BY timestamp DESC LIMIT 10;

MQTT Testing

# Subscribe to all topics (cloud broker)
docker exec mqtt-cloud mosquitto_sub -t "projects/#" -v

# Subscribe to all topics (local broker)
docker exec mqtt-local mosquitto_sub -t "projects/#" -v

# Publish test message
docker exec mqtt-local mosquitto_pub \
  -t "projects/factory-a/production/sensor-001/temperature" \
  -m '{"value":22.5,"timestamp":"2024-01-01T12:00:00Z","device":"sensor-001","metric":"temperature","unit":"celsius"}'

Troubleshooting

Services won't start

Check if ports are already in use
Verify Docker and Docker Compose versions
Check logs: docker-compose logs

No data appearing

Check MQTT publisher is running: docker-compose ps mqtt-publisher
Check MQTT bridge is forwarding: docker-compose logs mqtt-bridge
Verify API core is subscribed: docker-compose logs api-core
Check database connection: docker-compose logs postgres

API returns errors

Ensure PostgreSQL is healthy: docker-compose ps postgres
Check API logs: docker-compose logs api-core
Verify database migrations ran: docker exec mqtt-postgres psql -U iot_user -d iot_platform -c "\dt"

Stopping the Platform

# Stop all services
docker-compose down

# Stop and remove volumes (WARNING: deletes all data)
docker-compose down -v

Production Deployment

For production deployment:

Update security settings:
- Change default passwords
- Enable MQTT authentication
- Configure SSL/TLS for MQTT and HTTP
- Set up proper firewall rules
Configure reverse proxy:
- Set up proper domain names
- Enable HTTPS with Let's Encrypt
- Configure rate limiting
Database:
- Set up regular backups
- Configure connection pooling
- Enable query optimization
Monitoring:
- Set up Grafana alerts
- Configure log aggregation
- Monitor resource usage

Support and Feedback

This is a POC/Demo project. For questions or issues, please contact the development team.

License

Proprietary - Internal Use Only

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.claude		.claude
services		services
.env.example		.env.example
.gitignore		.gitignore
DEPLOYMENT.md		DEPLOYMENT.md
Makefile		Makefile
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
TESTING.md		TESTING.md
docker-compose.yml		docker-compose.yml

AllenSchmidt/demo-mqtt-dashboard

Folders and files

Latest commit

History

Repository files navigation