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.
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.
- 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
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/apiGET /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.
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.
| 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 |
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
- 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.
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.
This project is licensed under the GNU General Public License version 3. See LICENSE.