BSSCI Service Center

Operational control plane for MIOTY base stations and sensors, with secure TLS ingestion, MQTT integration, tenant-aware management, topology mapping, runtime monitoring, and admin auditability.

What This Project Provides

• Secure base-station communication via BSSCI/TLS server.
• Sensor lifecycle operations:
  • create/update/delete
  • register
  • attach/detach to base stations
  • bulk workflows
• Base station inventory and runtime status management.
• Network workspace:
  • Coverage map (OpenStreetMap + floorplan)
  • Topology graph
  • GPS sync between map and device settings
  • missing-GPS assistant
• Dashboard with configurable layout widgets.
• System Health with runtime counters and telemetry panels.
• MQTT monitoring and test publish utilities.
• Tenant and user administration with RBAC scopes.
• Admin audit log stream and export.
• Optional storage/analytics integrations:
  • TimescaleDB (operational store + telemetry)
  • InfluxDB (legacy optional integration, disabled by default)
  • Grafana (dashboard integration/proxy)

In-App Documentation

Detailed docs are available directly in UI:

• Sidebar item: Documentation (bottom, above user profile)
• Route: /documentation

This is the primary user guide for page-level functionality and workflows.

High-Level Architecture

Base Stations
  -> TLS/BSSCI Server (TLSServer.py)
    -> Internal queues (backpressure + retry metrics)
      -> MQTT publish path
      -> Optional Timescale/Influx writes
        -> Web UI APIs (Flask)
          -> Dashboard / Network / Sensors / Base Stations / Health / Logs

Main UI Sections

• Dashboard
  • Live operational overview.
  • Layout customization (drag/resize where enabled).
• Sensors
  • Inventory, attach/detach, status, details.
• Base Stations
  • Base station inventory, state, metadata and certificates entry-point.
• Network Topology
  • Coverage mode + topology mode with link/issue filters.
• System Health
  • Runtime + telemetry reliability indicators.
• MQTT
  • Broker monitoring and publish test workflows.
• Logs
  • Runtime logs + admin audit logs (scope-based visibility).
• Administration (Access & Tenants)
  • Users, tenants, scoped admin actions.
• Configuration
  • Server, MQTT, storage, maintenance, optional modules.
• Certificates
  • TLS certificate management.

Security and Access Model

• Login-protected UI/API.
• Roles: admin/user/viewer.
• Admin scopes for granular permissions (user/tenant/config/audit operations).
• Tenant-aware filtering for non-admin data visibility.
• Admin users can be configured for global visibility.

Docker Deployment (Recommended)

Use docker-compose.yml in this repository.

Quick Start

docker compose up -d --build

Default exposed services (as configured):

• Service Center UI: http://localhost:5056
• TLS server: localhost:8000
• TimescaleDB: localhost:5432
• Grafana: http://localhost:3000

For detailed Docker setup, see README-Docker.md.

Local Run (Without Docker)

pip install -r requirements.txt
python web_main.py

Open http://localhost:5000 (unless configured otherwise).

Configuration

Configuration is split between:

• .env (runtime/env integration settings)
• bssci_config.py (core server defaults)
• inventory/runtime JSON files:
  • endpoints.json
  • base_stations.json
  • coverage_positions.json
  • users.json (recovery fallback only for access bootstrap/import)
  • tenants.json (seed/recovery input for tenant registry)

Important integration families:

• MQTT
• TimescaleDB
• InfluxDB
• Grafana proxy/embed

Data and State Files

Typical persisted state:

• base_stations.json (BS inventory)
• endpoints.json (sensor inventory/config)
• coverage_positions.json (map coordinates)
• logs/ (runtime logs)

DB-First Access and Tenant Registry

Phase 2.1 introduces DB-first storage for:

• users
• tenant registry metadata
• admin audit log

Primary storage now lives in the operational database tables:

• app_users
• tenant_registry_meta
• admin_audit_log
• app_config_state

Bootstrap and recovery rules:

• users.default.json
  • seed source only
  • used for first bootstrap of default accounts on a clean clone
• users.json
  • recovery/import fallback only
  • no longer the primary runtime store for users
• tenants.json
  • tenant seed/recovery input
  • no longer the primary runtime registry when DB-first storage is enabled

Operational guidance:

• Back up the database as the primary source of truth for users, tenant registry and admin audit.
• Keep users.default.json versioned in Git as bootstrap seed content.
• Treat users.json and tenants.json as recovery inputs, not as authoritative runtime state.

Reliability Features

• Queue depth metrics for runtime backpressure.
• Retry policy for asynchronous write/publish paths.
• DB write latency observations.
• MQTT reconnect tracking.
• Admin audit trail for critical actions.

These are surfaced in monitoring APIs/UI and can be forwarded to external alerting.

Backup and Restore

Included scripts:

• scripts/backup.ps1
• scripts/restore.ps1
• scripts/deploy.ps1

Suggested backup scope:

• TimescaleDB data
• configuration files (.env, docker-compose.yml, bssci_config.py)
• DB-first access/tenant/audit state (app_users, tenant_registry_meta, admin_audit_log, app_config_state, notification delivery log, alert state/history)
• recovery/seed files (users.json, tenants.json, alerts.json, alert_state.json, alert_events.json, users.default.json, endpoints.default.json, base_stations.default.json, alerts.default.json, viewer_demo_telemetry.py)
• certificates (certs/)
• admin audit fallback file (logs/admin_audit.jsonl) when present

See README-Docker.md for practical commands and examples.

Testing

Test directory:

• tests/

Critical-flow coverage includes areas like:

• attach/detach
• GPS sync behavior
• tenant filtering
• MQTT test publish path
• audit log flows

Run tests (example):

pytest -q

Common Operational Notes

• If map positions and device GPS differ, run save/sync workflow in Network section.
• If sensor shows BS: none after attach, verify attach response and tenant filters.
• If telemetry is missing, check:
  • sensor registration
  • attach mapping
  • MQTT status
  • queue/retry metrics
  • logs

Repository Structure (Key Files)

• web_ui.py - Flask routes, API endpoints, auth, UI backend logic
• web_main.py - application startup
• TLSServer.py / tls_server.py - transport/protocol handling
• mqtt_interface.py - MQTT integration
• templates/ - web pages
• docker-compose.yml - container stack
• grafana/ - provisioning and dashboards
• timescaledb/ - initialization SQL

Notes for Customized Deployments

This project is actively customized for specific operational workflows. Treat automated "platform update" semantics as optional and prefer Git-based controlled releases in production.

License

See LICENSE.