Skip to content
aethera-deeptechPublic

About

Backend of an energy audit dashboard for small businesses in Indonesia

Topics

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

646 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Backend

CI Security Docker Docker Hub mirror Config lint Performance DAST DAST active Vale Fuzz Mutation Links

Release License Go version

API Docker pulls Docker image size GHCR

Last commit Conventional Commits Renovate

codecov OpenSSF Scorecard

Backend of an energy audit dashboard for small businesses (UMKM) in Indonesia, built for the UNS Innovation Hackathon 2026. The dashboard is in the frontend repository and its interface is in Indonesian.

Status

The service is built and runs in production. It is a Go program with a PostgreSQL database that serves a JSON API under /v1 for the dashboard and a device API under /device/v1 for the gateways. The contract is openapi.yaml, and docs/api.md explains the decisions behind it. ROADMAP.md lists what is done and what is planned.

Stack

  • Go with Fiber v3 and pgx
  • PostgreSQL, with SQL migrations that are embedded in the binary and applied when the service starts
  • Settings from environment variables, read once at start
  • Reports as one page of PDF, made in the service
  • Errors to Sentry and metrics to Prometheus or Grafana Cloud, both optional

Quick start

The service needs a PostgreSQL that it can reach. It does not read a .env file, so set the variables in your shell. DB_HOST, DB_NAME, DB_USERNAME and DB_PASSWORD are required, and the mail settings are only required in production, because a development run logs the mails instead of sending them.

export DB_HOST=localhost DB_NAME=aethera DB_USERNAME=aethera DB_PASSWORD=change-me DB_SSL_MODE=disable
go run ./cmd/api

GET /healthz reports the state of the database and the mail setting, and answers 503 when the database is down. GET /readyz is the check that a copy is ready for traffic. Operations explains the production setup with two copies behind a reverse proxy.

Configuration

Every setting is an environment variable, and .env.example lists all of them with their comments. The ones that matter most are these.

Variable Default What it does
APP_ENV development production turns on the stricter checks, such as an https APP_ORIGIN and a mail server and sender
APP_PORT 8080 The port of the API
APP_ORIGIN http://localhost:5173 The one origin that CORS allows, and the base of the links in the emails
TRUST_PROXY false Read the client address from PROXY_HEADER when a reverse proxy sits in front. The header is accepted only from private and loopback addresses, so also set TRUST_PROXY_CIDRS to the address of the proxy, or another container on a shared network can set the client address of the rate limits
DB_HOST, DB_NAME, DB_USERNAME, DB_PASSWORD required The PostgreSQL connection. DB_PORT is 5432 unless it is set
DB_SSL_MODE require, and disable in the example The mode of the connection. Use disable only on a private Docker network or on your own machine
DB_MAX_CONNS 8 The pool size of one copy
SMTP_HOST, SMTP_PORT, SMTP_SECURITY, SMTP_FROM_ADDRESS see the file The mail server for the verification, reset and account deleted mails
SENTRY_DSN empty An empty value switches error reports off
METRICS_ADDRESS empty The address of the Prometheus listener. Empty switches it off

The settings of Alloy live in grafana/alloy/.env, see Monitoring.

Documentation

Page What it answers
API The decisions behind the API, such as the sessions, the status of a device, the anomalies, the tips and the relay
openapi.yaml The full contract of every route
Errors Every error code, its status and what the client should do
Firmware guide The protocol of the gateway, with the limits and the relay commands
Architecture How the packages fit together and which jobs run
Data model The tables and how long the data stays
Security The threats, the measures and the known limits
Privacy What is kept, for how long, who can read it and how it is deleted
Operations How to run and update the service on a server
Monitoring The Grafana files, the alerts and the dashboards
CI/CD Every workflow and every required check
Testing How the tests run, which workflows start the whole stack and which run on a schedule
FAQ The words of the app and the answers to the questions that come up most
Decision records Why the repository merges with merge commits, who creates tags, which checks gate a merge and how images are signed
ROADMAP.md What is done and what is planned

Project layout

cmd/api            The entry point of the service
internal/          The packages of the service, one folder for each part
  api              Errors, the shared middleware and the access log
  app              Wires the packages to the routes
  auth             Accounts, sessions, password reset and the rate limits
  business         The settings of a business
  device           Pairing, rooms and the views of a device
  gateway          Enrollment, the intake of readings, the rollups and the anomaly rules
  relay            The commands and the schedules of a plug
  tips             The tips and the check of a saving
  home, report     The home screen and the weekly and monthly reports
  production       The production records of a business
  config           Settings from the environment
  database         The connection and the migrations
  server, mail, logging, metrics, errorreport, healthcheck, janitor   Support for running the service
  testutil, explain   Helpers for the tests and the query plan tool
docs/              The pages listed above
grafana/           Alloy, alert rules and dashboards
k6/, smoke/        The performance test and the smoke test
scripts/           The rolling update script

How it fits together

  • Each account has one business, and the data of a business hangs off one business row, so more people can join a business later.
  • The dashboard calls the API with a session cookie.
  • The devices of a business reach the service through one gateway over HTTPS, see the firmware guide.
  • The service works out the tips, the anomalies, the bill so far and the monthly and weekly reports from the readings.
  • A Docker image is published signed to GitHub Container Registry and mirrored to Docker Hub. Operations explains how to run it.
  • Release Please makes the version and the changelog.

Contributing

Read CONTRIBUTING.md before you open a pull request. The checks and the rules of the main branch are described in docs/ci-cd.md. Report security problems privately as described in SECURITY.md. Everyone who takes part follows the Code of Conduct.

License

This project is licensed under the GNU General Public License version 3. See LICENSE.

About

Backend of an energy audit dashboard for small businesses in Indonesia

Topics

Resources

Code of conduct

Contributing

Security policy

Accessibility

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages