Complete HDT-AF System Component Diagram (UML 2.5 Compliant)¶
This document presents the complete component architecture of the HDT-AF framework (Human Digital Twin - Autonomous Framework) in formal compliance with the UML 2.5 (Component Diagram) specification, covering the reactor's Maven modules, generic experiment components, provided/required interfaces, and external infrastructure.
1. UML 2.5 Component Diagram¶
Ver código-fonte PlantUML
@startuml "HDT-AF - Complete Component Diagram"
!theme plain
skinparam componentStyle uml2
skinparam packageStyle rectangle
skinparam shadowing false
title Complete Component Diagram — HDT-AF System (UML 2.5, 21 reactor modules)
' ─── PROVIDED / REQUIRED INTERFACES ───
interface "Admin REST & SSE API" as HTTP_API
interface "MQTT v5 Protocol\n(IoT & FL Topics)" as MQTT_Broker_IF
interface "Fabric Chaincode Contract" as Fabric_Ledger_IF
interface "Docker Engine Socket API" as Docker_Socket_IF
interface "DataComponent & TimeSeries API" as DataComponent_IF
interface "Artifact Storage API" as Artifact_IF
interface "Governance Ledger Mirror" as Chaincode_IF
package "Management Interface" as Sub_Frontend {
[Admin Web Frontend\n(React / Vite SPA)] as AdminWeb
}
package "External Infrastructure" as Sub_External {
node "MQTT Broker\n(Eclipse Mosquitto TCP:1883)" as BrokerMQTT
node "Hyperledger Fabric Peer\n(Peer, Orderer & Chaincode)" as FabricPeer
node "Docker Engine\n(Container Execution Runtime)" as DockerDaemon
}
package "Management & Monitoring" as Sub_Admin {
[federated-rest-api\n(AdminWebServer, DockerParticipantService)] as RestAPI
[federated-simulator\n(MqttDatasetReplaySimulator, CsvSimulationSource)] as Simulator
}
package "Federated Core & Orchestration" as Sub_CoreFL {
[federated-orchestrator\n(AdminMonitoringService, RoundScheduler)] as Orchestrator
[federated-aggregator\n(FedAvg, MqttClientUpdateCollector)] as Aggregator
[federated-client\n(FederatedClientService, PreflightValidator)] as ClientService
}
package "Storage & Artifacts" as Sub_DataStorage {
[federated-local-cdm\n(DataComponent, SqliteTimeSeries, ModelStore)] as LocalCDM
[federated-package-experiment-service\n(LocalArtifactExperimentService)] as ArtifactService
[federated-experiment-packager\n(HDTPACK + HDTSIM Package Service)] as ExpPackager
}
package "Governance & Chaincode" as Sub_Governance {
[federated-chaincode\n(ClientConsentChaincode, ExperimentContractChaincode, FederatedExperimentChaincode, FabricBridge)] as CCFedExperiment
}
package "Foundation & Communication" as Sub_Foundation {
[federated-common\n(MqttEnvelope, Codecs, HMAC Signatures)] as Common
[federated-experiment-sdk\n(ExperimentContract & DataSchema Spec)] as ExpSDK
[federated-containers\n(PahoMqttGateway)] as MqttPaho
}
package "Research Modules (Generic)" as Sub_Experiments {
[Generic Federated Experiment Module\n(TrainingLocalModel, Session & MLP)] as GenericExperiment
[Generic Docker Container Participants\n(DockerClientDaemonApp, DockerAggregatorDaemonApp)] as DockerParticipants
[Generic MQTT Simulation Adapter\n(SimulationAdapter & Replay)] as SimulationAdapter
[Generic Benchmark Submodule\n(Metrics, Evaluation, and Comparison)] as BenchmarkModule
[federated-system-tests\n(End-to-End Test Suite)] as SystemTests
}
' ─── PROVIDED INTERFACES ───
RestAPI -up- HTTP_API
BrokerMQTT -up- MQTT_Broker_IF
FabricPeer -up- Fabric_Ledger_IF
DockerDaemon -up- Docker_Socket_IF
LocalCDM -up- DataComponent_IF
ArtifactService -up- Artifact_IF
CCFedExperiment -up- Chaincode_IF
' ─── REQUIRED INTERFACES («use») ───
AdminWeb ..> HTTP_API : «use»
RestAPI ..> Fabric_Ledger_IF : «use»
RestAPI ..> Docker_Socket_IF : «use»
MqttPaho ..> MQTT_Broker_IF : «use»
Simulator ..> MQTT_Broker_IF : «use»
DockerParticipants ..> MQTT_Broker_IF : «use»
' ─── INTERNAL REACTOR RELATIONS («call», «use», «delegate») ───
RestAPI --> Orchestrator : «delegate»
RestAPI --> Simulator : «delegate»
Orchestrator ..> Chaincode_IF : «call»
Orchestrator ..> Aggregator : «use»
ClientService ..> DataComponent_IF : «use»
ClientService ..> CCFedExperiment : «use consent»
Aggregator ..> Artifact_IF : «use»
' ─── FOUNDATION AND SDK RELATIONS ───
LocalCDM ..> Common : «use»
ArtifactService ..> LocalCDM : «use»
CCFedExperiment ..> Common : «realize»
MqttPaho ..> Common : «use»
ExpSDK ..> Common : «use»
' ─── GENERIC EXPERIMENTS LINKED TO CORE INTERFACES ───
GenericExperiment ..> ExpSDK : «use»
GenericExperiment ..> DataComponent_IF : «use»
DockerParticipants ..> ClientService : «use»
DockerParticipants ..> Aggregator : «use»
SimulationAdapter ..> Simulator : «use»
BenchmarkModule ..> GenericExperiment : «use»
SystemTests ..> HTTP_API : «use»
@enduml
2. Detailed Description of the Maven Modules (22 Reactor Modules)¶
| Maven Module | Main Responsibility | Key Dependencies |
|---|---|---|
federated-common |
Fundamental abstractions of the ecosystem: MQTT envelopes (MqttEnvelope), HMAC signatures, hashing utilities (SHA-256), JSON codecs, and domain exceptions. |
Jackson Databind, Java 25 |
federated-experiment-sdk |
Base interfaces and models for developing federated experiments: experiment contracts, data schemas, and task types. | federated-common |
federated-local-cdm |
Local data access component (DataComponent), snapshot generator, time-series SQLite store (SqliteTimeSeriesStore), and model store (ModelArtifactStore). Guarantor of MQTT provenance. |
federated-common, SQLite JDBC |
federated-chaincode |
In-memory consent, experiment-contract, and federated-experiment simulators (ClientConsentChaincode, ExperimentContractChaincode, FederatedExperimentChaincode), plus the Fabric bridge. |
federated-common |
federated-package-experiment-service |
Publication, storage, and portable resolution service for experiment artifacts (LocalArtifactExperimentService), with support for host-container root fallback. |
federated-local-cdm |
federated-digital-twin-broker |
Local digital-twin bridge and loopback REST+SSE transport (EmbeddedTwinBroker, DigitalTwinBridge, RestSseGateway, EmbeddedRestSseBroker). |
federated-common, federated-containers, federated-client |
federated-experiment-packager |
Utility and CLI for immutable experiment archives (.hdtpack.zip) and simulation dataset archives (.hdtsim.zip), including manifests, training code, dataset schema, and partitioning. |
federated-experiment-sdk, federated-common |
federated-client |
Federated client service (FederatedClientService): performs contract acceptance, runs the preflight check, and orchestrates local training epochs. |
federated-local-cdm, federated-chaincode |
federated-orchestrator |
Central federated learning orchestrator: eligible client selection, round configuration issuance (RoundConfig), and quorum synchronization. |
federated-chaincode |
federated-aggregator |
Federated aggregation algorithm (FedAvgAggregationService), weighting strategies, and MQTT update collector (MqttClientUpdateCollector). |
federated-package-experiment-service |
federated-containers |
MQTTv5 connector based on the Eclipse Paho library (PahoMqttGateway), providing mTLS, QoS 1 support, and automatic reconnection. |
federated-common, Paho MQTT v5 |
federated-rest-api |
HTTP/REST and SSE web server (AdminWebServer), Docker container manager (DockerParticipantLaunchService), and monitoring service (AdminMonitoringService). |
federated-orchestrator, federated-aggregator, federated-containers |
federated-simulator |
Dataset replayer to MQTT topics (MqttDatasetReplaySimulator), generic CSV engine (CsvDatasetSimulationSource), and simulation package executor (SimulationDataPackagePlayer). |
federated-local-cdm, federated-experiment-packager |
federated-system-tests |
System integration test suite, validating concurrency, the round cycle, LGPD contracts, and ledger compliance. | federated-rest-api, JUnit 5 |
research/experiments/* (Generic) |
Autonomous research and federated experiment modules (e.g., classification, anomalies, ergonomic risk, time series): implement the local model (TrainingLocalModel), neural network/learning algorithm, federated session, and simulation adapters. |
federated-experiment-sdk, federated-local-cdm |
research/experiments/*/benchmark (Generic) |
Submodules for performance evaluation, benchmarking, hyperparameter optimization, and comparison of federated aggregation strategies. | Corresponding experiment module |
3. Interfaces and External Integration Points¶
- MQTT 5 Broker (Mosquitto):
- IoT Topics: Ingestion of time series and events in CDM format (
iot/clients/{clientId}/...). -
FL Topics: Exchange of control messages,
RoundConfig,ClientUpdatePayload, andAggregationStatus(fl/experiments/{expId}/rounds/...). -
Hyperledger Fabric (Blockchain Governance Layer):
- Smart Contracts / Chaincodes:
FederatedExperimentSmartContract,FederatedContractSmartContract,ConsentSmartContract. -
Provenance Auditing: Stores the TxId, the contract specification hash, the training code hash, local model hashes, and Global Model versions.
-
Docker Engine & Persistent Containers:
-
Isolated Clients and Aggregators:
DockerParticipantLaunchServiceprovisions isolated Docker containers to run clients (DockerClientDaemonApp) and aggregators (DockerAggregatorDaemonApp), dynamically mounting library volumes and the local SQLite database volume at/app/data/timeseries.db. -
Admin Web Dashboard (Admin Web Frontend):
- Real-Time Monitoring: Connects via Server-Sent Events (SSE)
/api/events/streamto update round progress, the participant graph view, the blockchain explorer, and simulation triggering.