Ir para o conteúdo

Canonical Project Context

Mission

HDT-AF is a Java platform for privacy-conscious federated learning in human and industrial digital-twin settings. It combines experiment contracts, local data access, client-side training, round coordination, aggregation, MQTT communication, and Hyperledger Fabric audit records.

Source layout and build

The root Maven reactor targets Java 25 and includes 15 platform modules, five experiment modules, and two benchmark modules. The Android app is a separate Gradle project. The Vite admin frontend is a separate npm workspace and is not in the Maven reactor. The checked-out module directories are independent Git repositories ignored by the root repository, not Git submodules; see the module inventory.

Build and script entry points are in modules/scripts/. The root scripts path is a compatibility symlink to that independent repository.

sh scripts/compile.sh
sh scripts/run-tests.sh --fast

The project currently requires a JDK that supports Java 25. Android builds have their own Gradle/JDK requirements; consult the Android client README. Test counts change with the checkout; use the Maven/Surefire output rather than a count stored in documentation.

Main runtime facts

  • The platform modules and their responsibilities are listed in docs/modules.md; component details are indexed in docs/components/README.md.
  • The admin monitor/API is federated-rest-api and listens on port 8088 by default.
  • The supported ledger mode is BLOCKCHAIN. Fabric configuration and credentials must be available; legacy values accepted by the launcher are normalized to blockchain and do not provide an in-memory or failure-tolerant mode.
  • Docker Compose configures MQTT 5 over TLS/mTLS on port 8883. Runtime security depends on using the supplied TLS configuration/material. Plain tcp:// remains available only when explicitly configured for local tests or legacy development.
  • MQTT transport implementation and TLS configuration live in federated-containers; shared messages, envelopes, and topic definitions live in federated-common.
  • The round protocol and IoT data ingestion use MQTT. RestSseGateway remains only for the internal local-digital-twin microbroker hop.
  • DataComponent in federated-local-cdm is the application entry point for local experiment data. Its production time-series store is SQLite, populated by verified MQTT ingestion.
  • The monitor bootstrap registers DT, HAR, and ECG. The packaging script supports ECG, MIMIC, MNIST, and ergonomic-risk experiment packages. Synthetic smoke validation has its own runner. See docs/components/13-research-experiments.md.
  • Model inference packages are managed by federated-model-inference; trained experiment packages and Android client algorithm packages have separate formats handled by federated-experiment-packager.
  • Package deployment executes experiment code in a separate operating-system process. The upload endpoint has no authentication of its own and the process has no resource limits; keep the monitor on a trusted network.
  • The package-artifact service currently stores files under its configured artifact root. The architectural goal that Fabric be the only permanent federated-core store is not yet fully met; see backlog item BL-298.

Project invariants

  • Preserve Java for the federated core, MQTT 5 for federated communication, and Hyperledger Fabric for audit/governance.
  • Raw client data stays local by default. Any centrally configured MQTT archive is opt-in and requires an approved access and retention policy.
  • Do not train without an accepted contract, a valid preflight, and compatible runtime support.
  • Do not bypass DataComponent to read a local experiment dataset.
  • Do not publish a client update directly to the aggregator-facing topic; the orchestrator relay owns that hop.
  • Verify both the envelope signature and payload integrity before processing an MQTT message.

The canonical shared rules and development workflow are in .agents/shared-rules.md and .agents/workflow.md. Technical documentation starts at docs/README.md.