Ir para o conteúdo

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

Diagrama PlantUML 1

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

  1. MQTT 5 Broker (Mosquitto):
  2. IoT Topics: Ingestion of time series and events in CDM format (iot/clients/{clientId}/...).
  3. FL Topics: Exchange of control messages, RoundConfig, ClientUpdatePayload, and AggregationStatus (fl/experiments/{expId}/rounds/...).

  4. Hyperledger Fabric (Blockchain Governance Layer):

  5. Smart Contracts / Chaincodes: FederatedExperimentSmartContract, FederatedContractSmartContract, ConsentSmartContract.
  6. Provenance Auditing: Stores the TxId, the contract specification hash, the training code hash, local model hashes, and Global Model versions.

  7. Docker Engine & Persistent Containers:

  8. Isolated Clients and Aggregators: DockerParticipantLaunchService provisions 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.

  9. Admin Web Dashboard (Admin Web Frontend):

  10. Real-Time Monitoring: Connects via Server-Sent Events (SSE) /api/events/stream to update round progress, the participant graph view, the blockchain explorer, and simulation triggering.