Back to Projects

SynergyGEOS

DjangoAstroJSReactJSMySQL

Overview

Synergy Geos is a building energy-accounting platform composed of a Django REST Framework backend and an Astro + React server-rendered frontend. It models buildings, housing units, metering devices, and time-series consumption readings; imports device data from remote files and authenticated JSON uploads; schedules retryable background processing with SMS escalation; and exposes role-aware reporting, visualization, and administration workflows. The platform supports administrators, building administrators, and property owners through a multilingual portal with dashboards, charts, alarm calendars, spreadsheet imports, and consumption-report management.

Screenshots

SynergyGEOS — screenshot 1SynergyGEOS — screenshot 2SynergyGEOS — screenshot 3SynergyGEOS — screenshot 4

Objectives

  • ▸ Provide a multi-tenant energy-accounting platform for tracking utility and heat consumption across buildings, housing units, and metering devices
  • ▸ Enforce role-based and row-level access for administrators, building administrators, and property owners
  • ▸ Ingest device readings from remote FTP files, authenticated JSON payloads, and Italian-formatted spreadsheet imports
  • ▸ Normalize raw readings into per-device, per-house, and per-building time-series data
  • ▸ Aggregate consumption over configurable daily, weekly, bi-weekly, monthly, quarterly, and yearly periods
  • ▸ Automate remote data collection through a restart-safe database-backed task queue with retries and SMS failure escalation
  • ▸ Expose a documented JWT-authenticated REST API for resources, analytics, reports, alarms, uploads, and administration
  • ▸ Deliver a bilingual Astro and React portal with role-aware navigation, dashboards, charts, heatmaps, report management, and alarm scheduling
  • ▸ Support containerized local development and production-oriented Passenger deployment workflows

Architecture

Two-application repository. Backend: Django 3.2 with Django REST Framework, Simple JWT authentication, drf-spectacular OpenAPI documentation, Eloquent-style domain separation through dedicated account, user, core, unit, reading, alarms, elaborato, and basic Django apps, and MySQL 8 as the relational data store. Buildings contain housing units, housing units contain metering devices, and readings are maintained at device, house, and building levels. Data-ingestion scripts download and parse remote device files, decode M-Bus-style hexadecimal payloads, import external JSON data, and retain progress in model metadata. A custom database-backed AlarmTask queue dispatches Python functions through importlib and records pending, running, completed, or failed states; retry workflows can send Twilio SMS alerts. Security layers include JWT authentication, role-specific DRF permissions, queryset-level tenant filtering, and timestamped HMAC validation for unauthenticated JSON uploads. Frontend: Astro 4 in SSR mode with the Node standalone adapter, React 18 islands, Tailwind CSS, Axios, i18next, data visualization components, spreadsheet processing, and HTTP-only cookies managed through Astro actions. Docker Compose provides Django, MySQL, and phpMyAdmin for local development, while separate cPanel and Passenger configurations support deployment of the backend and frontend.

Key Features

  • ▸ JWT authentication with access-token refresh, token blacklisting, password-reset workflows, and administrator impersonation
  • ▸ Role-based permissions for administrators, building administrators, and property owners, combined with queryset-level filtering of nested tenant resources
  • ▸ CRUD APIs for buildings, houses, metering devices, building blocks, users, device readings, house readings, building readings, alarms, and consumption reports
  • ▸ Time-series aggregation across daily, weekly, bi-weekly, monthly, quarterly, and yearly intervals
  • ▸ Current-versus-previous-period consumption comparison and aggregated total endpoints
  • ▸ Selective visibility of reading history for standard users through scheduled first-of-month and mid-month sampling
  • ▸ Bulk spreadsheet import of Italian-keyed building, unit, device, and consumption data
  • ▸ FTP-based ingestion of remote device files with tabular parsing, hexadecimal M-Bus payload decoding, duplicate prevention, and resumable progress tracking
  • ▸ Authenticated JSON ingestion using HMAC-SHA256 headers and a five-minute timestamp-validity window
  • ▸ Database-backed AlarmTask scheduling with pending, running, completed, and failed states, parent-child task linkage, retry handling, and dynamic task dispatch
  • ▸ Twilio SMS escalation after repeated remote data-fetch failures, with phone-number normalization and delayed rescheduling
  • ▸ Consumption-report lifecycle with pending, approved, and rejected statuses, deterministic JSON data snapshots, and report audit logs
  • ▸ Dashboard statistics for buildings, units, devices, administrators, owners, residents, unlinked records, and monthly cohorts
  • ▸ Administrator-controlled execution of approved repository scripts through a REST endpoint
  • ▸ Public contact-form submission and role-restricted contact-management endpoints with filtering and sorting
  • ▸ Swagger UI, Redoc, and machine-readable OpenAPI schemas generated through drf-spectacular
  • ▸ Astro and React portal routes for buildings, houses, devices, readings, users, alarms, administrator management, and consumption-report creation, editing, and viewing
  • ▸ Visualization components including line, bar, donut, comparison, and calendar-heatmap charts
  • ▸ Excel upload interface, reusable data tables, summary cards, modal workflows, and alarm-creation calendar controls
  • ▸ Astro login, logout, and current-user actions that proxy backend JWT operations and store authentication data in HTTP-only cookies
  • ▸ Centralized Axios error handling with localized alerts for authentication, authorization, server, and network errors
  • ▸ Italian and English localization through i18next, with an optional local Ollama-based translation utility
  • ▸ Open-source local-development stack using Docker Compose, MySQL 8, Django, and phpMyAdmin
  • ▸ Separate backend and frontend deployment definitions for Python Passenger and Node-based Astro SSR

Challenges

  • ▸ Enforcing multi-tenant access across nested relationships in which a device belongs to a house, a house belongs to a building, and visibility depends on the current user's assigned role and ownership
  • ▸ Maintaining consistent per-device, per-house, and per-building aggregates without double counting when duplicate device readings are received
  • ▸ Resuming FTP ingestion after interruption without downloading and processing previously imported remote files
  • ▸ Parsing vendor-specific tabular files and hexadecimal M-Bus payloads into normalized application entities and measurements
  • ▸ Providing restart-safe scheduled processing without Celery through a persistent database task queue, dynamic task dispatch, retry chains, and failure escalation
  • ▸ Producing deterministic consumption reports by snapshotting related device and reading data at save time rather than relying only on mutable live records
  • ▸ Protecting a login-free machine-to-machine upload endpoint through timestamped HMAC signatures, request-age checks, and malformed-payload handling
  • ▸ Restricting complete reading history for standard users while exposing representative measurements near the first and fifteenth day of each month
  • ▸ Coordinating authentication across separately deployed frontend and backend applications by proxying JWT operations through Astro actions and HTTP-only cookies
  • ▸ Supporting Italian-keyed spreadsheets, localized date formats, and bilingual frontend content throughout import and presentation workflows
  • ▸ Implementing flexible period comparisons and aggregation for conventional and custom bi-weekly time buckets
  • ▸ Preserving task ancestry and retry state across dynamically scheduled parent and child AlarmTask records

Outcomes

  • ▸ Delivered a documented REST API covering authentication, users, buildings, housing units, devices, readings, alarms, consumption reports, contact forms, media, data uploads, dashboard statistics, and administrative scripts
  • ▸ Implemented a persistent task lifecycle with pending, running, completed, and failed states, including automated retries and SMS escalation
  • ▸ Added tested HMAC and timestamp validation for external JSON uploads, covering missing headers, stale requests, invalid signatures, and malformed JSON
  • ▸ Built time-range-aware consumption aggregation, historical comparisons, and availability endpoints with automated backend test coverage
  • ▸ Established role-aware resource access through both permission classes and filtered querysets for the complete building-to-device hierarchy
  • ▸ Created an Astro and React SSR portal with role-specific dashboards, CRUD workflows, consumption charts, calendar heatmaps, spreadsheet upload, alarm scheduling, and report management
  • ▸ Implemented resumable device-data ingestion from FTP-hosted files and normalized imports across device, house, and building reading levels
  • ▸ Provided bilingual Italian and English UI infrastructure and an optional offline translation workflow using a locally hosted language model
  • ▸ Packaged the backend for local use with Python, Django, MySQL, and phpMyAdmin through Docker Compose
  • ▸ Prepared separate backend and frontend deployment paths using Passenger, a standalone Astro Node adapter, and an Express SSR entry point