System Overview

High-Level Architecture

ECTS high-level architecture

Runtime Composition

Backend startup (com.ects.backend.Main) creates the Guice injector and starts lifecycle services:

  • ScheduleManager
  • ServerManager
  • WebServer
  • BroadcastService
  • KafkaConsumerDelegate
  • JourneyMonitor

The WebServer hosts:

  • REST API on /api/* (Jersey)
  • WebSocket endpoint /api/socket
  • Static web app assets (configured by web.path)

Core Responsibilities by Tier

Device/Protocol tier

  • Accepts protocol-specific payloads
  • Decodes telemetry and lock signals
  • Updates device/session states

Domain/API tier

  • Resource classes under api/resource
  • CRUD + domain actions (journeys, inventories, routes, alerts)
  • Role-based access control enforced via JWT + @RolesAllowed

Persistence tier

  • SQL-backed storage via DatabaseStorage
  • Liquibase migration startup in DatabaseModule
  • Change-log capture for audited entities

Portal tier

  • React app with route modules (cargo, journeys, routes, inventory, alerts, etc.)
  • Redux Toolkit for state slices and async UI updates
  • OIDC/JWT token handling and route-level role gating

Key Integration Characteristics

  • Backend serves both API and static frontend if configured
  • Portal calls backend through configured base URL (VITE_BACKEND_URL)
  • Portal uses REST + websocket for operational views
  • Security is bearer-token based, with role checks in backend resources and frontend route wrappers