Backend Developer Guide

Backend Codebase Scope

Root path: ects-backend/

Primary runtime stack:

  • Java + Gradle
  • Jetty + Jersey
  • Guice DI
  • HikariCP + PostgreSQL
  • Liquibase migrations

Package Inventory (Selected)

Package Approx Java File Count Purpose
protocol 648 Device protocol decoding/encoding
api 60 REST/web API integration
model 57 Domain models and business rules
handler 40 Event/network handling pipelines
reports 23 Report generation/export
storage 17 Persistence abstractions and SQL layer
session 15 Device/user session management
web 9 Jetty/Jersey server wiring

Request Path Through the System

  1. HTTP request enters Jetty WebServer
  2. Jersey dispatches to resource class under api/resource
  3. JwtAuthenticationAuthorizationFilter validates bearer token when auth is enabled
  4. RolesAllowedDynamicFeature enforces method/class role annotations
  5. Resource calls domain/service/storage logic
  6. DatabaseStorage executes SQL via QueryBuilder
  7. Response serialized and returned

Entry and Lifecycle

Entry class: src/main/java/com/ects/backend/Main.java

Important startup behavior:

  • Config file selection (debug.xml fallback)
  • Guice module construction (MainModule, DatabaseModule, WebModule)
  • Service startup/shutdown hooks
  • Runtime logging of OS/JVM/memory details

Data and Migration Layer

DatabaseModule:

  • Builds Hikari datasource from config keys
  • Optionally loads external DB driver jar
  • Runs Liquibase changelog update at startup
  • Uses lock wait and fails fast on changelog lock issues

DatabaseStorage:

  • Generic CRUD over annotated storage models
  • Condition/query formatting and parameter binding
  • Permission mapping helpers
  • Change log recording for audited entities

Domain Hotspots

Device lifecycle and state

  • Device + connection states are managed across session and model layers
  • Related logic spans model/Device.java, session/ConnectionManager.java, state processors
  • Maintenance and decommission actions mutate both device and inventory state

Journey operations

  • Journey creation, lifecycle, and event attachment are concentrated in JourneyResource + model logic
  • Journey endpoints include preparation flows, active/flagged/completed views, and detail/event lookups

Inventory operations

  • Inventory creation, assignment, unassignment, and authority binding are in InventoryResource
  • Inventory status transitions support in-store/in-use/maintenance/decommission flow

Configuration Strategy

Config class (config/Config.java) supports:

  • XML property files (debug*.xml)
  • Optional environment-variable override mode (config.useEnvironmentVariables)

Important runtime keys include:

  • DB connection and changelog keys
  • Web server path/port/debug keys
  • Auth/openid keys
  • Kafka, Redis, MinIO keys

When adding a new backend feature:

  1. Define/extend model class and storage annotations
  2. Add migration in schema/ and wire into changelog master
  3. Add/extend resource endpoint under api/resource
  4. Add role guards with @RolesAllowed
  5. Update OpenAPI and governance generator outputs
  6. Add unit/integration tests in src/test/java