Simplified HDT-AF System Component Diagram (PlantUML)¶
This document presents the simplified version of the Component Diagram of the HDT-AF framework (Human Digital Twin - Autonomous Framework), described using the formal syntax of the PlantUML (UML 2.5 Component Diagram) specification.
The diagram visually makes explicit the architecture in 6 subsystems — including a dedicated Federated Client subsystem, kept structurally separate from the central Federated Core & Orchestration subsystem, since each runs as an independent instance per participant while the core runs once, server-side — and the provenance flow where simulation MQTT messages sent by federated-simulator are ingested by MqttTimeSeriesIngestor (federated-local-cdm) and securely consumed by federated-client.
1. PlantUML Specification (UML 2.5)¶
Ver código-fonte PlantUML
@startuml "HDT-AF - Simplified Component Diagram"
!theme plain
skinparam componentStyle uml2
skinparam packageStyle rectangle
skinparam shadowing false
title Simplified Component Diagram — HDT-AF System (UML 2.5)
' ─── PROVIDED AND REQUIRED INTERFACES ───
interface "Admin REST & SSE API" as IF_HttpAPI
interface "MQTT v5 Protocol\n(IoT CDDL & FL Topics)" as IF_MqttBroker
interface "Fabric Chaincode Contract" as IF_FabricLedger
interface "Docker Engine Socket API" as IF_DockerSocket
interface "DataComponent API\n(Local CDM / SQLite)" as IF_DataComponent
' ─── MANAGEMENT INTERFACE SUBSYSTEM ───
package "Subsystem Management Interface" {
[Admin Web Frontend\n(React / Vite SPA)] as AdminWeb
[federated-rest-api\n(AdminWebServer & DockerService)] as RestAPI
}
' ─── FEDERATED CORE SUBSYSTEM (server-side, single instance) ───
package "Subsystem Federated Core & Orchestration\n(server, 1 instance)" {
[federated-orchestrator\n(AdminMonitoringService & RoundScheduler)] as Orchestrator
[federated-aggregator\n(FedAvgAggregationService)] as Aggregator
}
' ─── FEDERATED CLIENT SUBSYSTEM (one independent instance per participant) ───
package "Subsystem Federated Client\n(1 instance per participant)" {
[federated-client\n(FederatedClientService & Preflight)] as ClientService
[federated-digital-twin-broker\n(EmbeddedTwinBroker & DigitalTwinBridge)] as TwinBroker
[federated-local-cdm\n(MqttTimeSeriesIngestor & DataComponent)] as LocalCDM
}
' ─── BLOCKCHAIN GOVERNANCE SUBSYSTEM ───
package "Subsystem Blockchain Governance" {
[federated-chaincode\n(Contract & Audit Chaincode)] as Chaincode
}
' ─── COMMUNICATION & SIMULATION SUBSYSTEM ───
package "Subsystem Communication & Simulation" {
[federated-containers\n(PahoMqttGateway)] as MqttGateway
[federated-simulator\n(MqttDatasetReplaySimulator)] as Simulator
}
' ─── EXTERNAL INFRASTRUCTURE ───
package "Subsystem External Infrastructure" {
node "MQTT Broker\n(Mosquitto)" as Mosquitto
node "Hyperledger Fabric Peer" as FabricPeer
node "Docker Engine" as DockerDaemon
}
' ─── INTERFACE REALIZATIONS ───
RestAPI -up- IF_HttpAPI
Mosquitto -up- IF_MqttBroker
FabricPeer -up- IF_FabricLedger
Chaincode -up- IF_FabricLedger
DockerDaemon -up- IF_DockerSocket
LocalCDM -up- IF_DataComponent
' ─── SIMULATION AND MQTT INGESTION CONNECTIONS (IOT → CLIENT FLOW) ───
Simulator ..> IF_MqttBroker : «publish»\n(mhub/{clientId}/service_topic/+)
LocalCDM ..> IF_MqttBroker : «subscribe & ingest»\n(MqttTimeSeriesIngestor -> timeseries.db)
ClientService ..> IF_DataComponent : «read authorized view»\n(AuthorizedTrainingView)
' ─── REST, ORCHESTRATION, AND BLOCKCHAIN CONNECTIONS ───
AdminWeb ..> IF_HttpAPI : «use»
RestAPI ..> IF_DockerSocket : «use»
RestAPI --> Orchestrator : «delegate»
RestAPI --> Simulator : «delegate»
Orchestrator ..> IF_FabricLedger : «call»
Orchestrator --> Aggregator : «coordinate»
ClientService ..> IF_FabricLedger : «verify»
MqttGateway ..> IF_MqttBroker : «use»
ClientService ..> MqttGateway : «publish update»\n(fl/experiments/...)
Aggregator ..> MqttGateway : «use»
' ─── LOCAL DIGITAL TWIN INTERFACE (ADR-002, BL-238) ───
TwinBroker ..> IF_MqttBroker : «bridge»\n(external MQTT5 <-> embedded MQTT 3.1.1)
TwinBroker --> ClientService : «trigger round»\n(executeRoundOnFinalizationSignal)
TwinBroker ..> IF_FabricLedger : «register decision»\n(registerTwinValidationDecision)
note right of TwinBroker
<b>Local access interface to the digital twin (ADR-002, BL-238):</b>
embedded MQTT microbroker (Moquette) in loopback per client.
DigitalTwinValidatorAdapter decides PROMOTE/REJECT/DEFER for the
candidate model before triggering federated-client — which
required zero changes. Coexists with the Docker executor.
end note
note right of LocalCDM
<b>LGPD Provenance Invariant:</b>
federated-client never accesses raw data directly.
MqttTimeSeriesIngestor consumes the broker's CDDL topics,
validates the HMAC signature, and persists to timeseries.db.
FederatedClientService reads the authorized view via DataComponent.
end note
@enduml
2. Description of Subsystems and Message Flows¶
| Subsystem | Component | Architectural Role & MQTT Flow |
|---|---|---|
| Communication & Simulation | federated-simulator |
Publishes dataset observations via MQTT on the client-scoped mhub/{clientId}/service_topic/+ CDDL topic (BL-237), plus lifecycle events on the still-global microbroker/cddl/event/object/+. |
| Federated Client | federated-local-cdm |
MqttTimeSeriesIngestor subscribes to each client's own mhub/{clientId}/service_topic/+ topic (structural isolation, BL-237), validates HMAC, and persists to the client's timeseries.db. Runs on the client's own node — never server-side. |
| Federated Client | federated-client |
FederatedClientService reads the authorized view (AuthorizedTrainingView) generated by DataComponent to train the local model. One independent instance per participant (1 Docker container/client). |
| Federated Client | federated-digital-twin-broker |
Local access interface to the digital twin (ADR-002, BL-238): embedded MQTT microbroker bridges the real external broker to a loopback broker, triggers federated-client rounds, and decides model promotion via LocalModelValidator. |
| Federated Core | federated-orchestrator |
Central orchestrator: manages quorum, eligible client selection, and round dispatch. Server-side, single instance. |
| Federated Core | federated-aggregator |
Federated model aggregation service (FedAvg) and consolidation of global weights via MQTT. Server-side, single instance. |
| Blockchain Governance | federated-chaincode |
Contract lifecycle and append-only audit trail chaincode, deployed on the Hyperledger Fabric peers — not part of either the core or the client process. |
| Management Interface | Admin Web / REST API |
SPA dashboard and HTTP REST/SSE server for monitoring and automated management of Docker containers. |
| External Infrastructure | MQTT Broker / Fabric / Docker |
Data transport services (Mosquitto), blockchain consensus (Fabric), and container isolation (Docker). |