Component Diagrams — HDT-AF¶
Updated on 2026-06-03 to reflect BL-045 through BL-053 (lifecycle management, LedgerPort, AdminHtmlLayout).
1. General Architectural Diagram¶
Ver código-fonte PlantUML
@startuml "HDT-AF - General Architectural Diagram"
!theme plain
skinparam componentStyle uml2
skinparam packageStyle rectangle
skinparam shadowing false
package "👨🔬 Researcher" as PESQUISADOR {
[🖥️ Web Monitor\n/experiments/new\n/lifecycle · /edit\n/clients · /blockchain] as MONITOR
[📡 JSON REST API\n/api/experiments\n/api/rounds] as API_REST
}
package "⚙️ Federated Framework — HDT-AF" as FRAMEWORK {
[🎯 Orchestrator\nRoundCoordinator\nsigned RoundConfig] as ORCH
[🔗 Aggregator\nFedAvg · FedMedian\nTrimmedMean · Krum · FedAdam] as AGG
[📦 Artifact Service\nLocalArtifactExperimentService\nArtifactRetentionPolicy (LGPD)] as ARTIFACT
}
package "📨 MQTT Bus (in-memory → TLS/mTLS)" as MQTT_BUS {
[fl/ — federated protocol\nroundConfig · clientUpdate\nmodelPublished] as MQTT_FL
[iot/ — IoT ingestion\nentities/observations\nentities/events] as MQTT_IOT
}
package "🤝 Federated Clients (N nodes)" as CLIENTES {
[Client 1\nFederatedClientService\nDataComponent\nTrainingLocalModel] as CLIENT1
[Client 2 ...] as CLIENT2
[Client N ...] as CLIENTN
}
package "🔗 Hyperledger Fabric" as BLOCKCHAIN {
[ExperimentContractChaincode] as CC_CONTRACT
[ClientConsentChaincode] as CC_CONSENT
[FederatedExperimentChaincode] as CC_EXP
[FabricCliLedgerMirror\nimplements LedgerPort] as LEDGER_MIRROR
}
package "💾 Local Data" as DATA {
[data/{client}/{exp}/\ndataset.csv · metadata.json\nobservations_ts.csv] as DATASET
[DataComponent\nLocalCdmRepository\nAuthorizedTrainingView] as CDM
}
MONITOR --> API_REST : HTTP 8088
MONITOR --> ORCH
MONITOR --> LEDGER_MIRROR : LedgerPort
ORCH --> MQTT_FL : RoundConfig signed
MQTT_FL --> CLIENT1 : subscribe
MQTT_FL --> CLIENT2 : subscribe
MQTT_FL --> CLIENTN : subscribe
CLIENT1 --> MQTT_FL : ClientUpdate signed
CLIENT2 --> MQTT_FL : ClientUpdate signed
CLIENTN --> MQTT_FL : ClientUpdate signed
MQTT_FL --> AGG : collect
AGG --> ARTIFACT : store
AGG --> MQTT_FL : GlobalModelPublication
LEDGER_MIRROR --> CC_CONTRACT
LEDGER_MIRROR --> CC_CONSENT
LEDGER_MIRROR --> CC_EXP
CLIENT1 --> CDM
CDM --> DATASET
MQTT_IOT --> CDM : ingest
@enduml
2. Simplified Component Diagram¶
Ver código-fonte PlantUML
@startuml "HDT-AF - Simplified Component Diagram"
!theme plain
skinparam componentStyle uml2
skinparam packageStyle rectangle
skinparam shadowing false
left to right direction
package "Researcher Interface" as UI {
[Web Monitor\nhttp://localhost:8088] as M
}
package "Federated Core" as CORE {
[Orchestrator\nRoundCoordinator] as O
[Aggregator\nFedAvgAggregationService] as A
[Federated Client\nFederatedClientService] as C
}
package "Infrastructure" as INFRA {
[MQTT Gateway\n(in-memory / broker)] as MQTT
[Hyperledger Fabric\n(LedgerPort)] as FABRIC
[Off-chain artifacts\nLocalArtifactExperimentService] as FILES
}
package "Local Data" as DATA {
[DataComponent\n(single access point)] as DC
[dataset.csv\nts_store.csv] as CSV
}
M --> O : lifecycle mgmt
M --> FABRIC : LedgerPort
O --> MQTT : RoundConfig HMAC
MQTT --> C
C --> DC
DC --> CSV
C --> MQTT : ClientUpdate HMAC
MQTT --> A
A --> FILES
A --> FABRIC : hash · URI
A --> MQTT : GlobalModel HMAC
@enduml
3. Detailed Component Diagram¶
Ver código-fonte PlantUML
@startuml "HDT-AF - Detailed Component Diagram"
!theme plain
skinparam componentStyle uml2
skinparam packageStyle rectangle
skinparam shadowing false
package "federated-rest-api (24 classes)" as ADMIN {
[AdminWebServer\n(HTTP router — 1,415 lines)] as AWS
[AdminMonitoringService\n(stateful: experiments, rounds, metrics)] as AMS
[AdminHtmlLayout\n(CSS · badge · row · tabs — static)] as AHL
[AdminApplicationBootstrap\n(factory: createMonitoringServiceWithPort)] as AAB
[AdminExperimentExecutor\n(stateful sessions)] as AEE
[ExperimentContractFactory\n(DRAFT builder with defaults)] as ECF
interface "LedgerPort\n12 lifecycle operations" as LP
[InMemoryLedgerPort\n(idempotent no-op — tests)] as ILMP
[FabricCliLedgerMirror\nimplements LedgerPort+FabricExperimentBridge] as FCLM
[ClientPseudonymService\n(LGPD Art. 13 — SHA-256 + salt)] as CPS
[TlsConfig\n(HttpsServer when ADMIN_TLS_KEYSTORE)] as TLS
}
package "federated-aggregator (11 classes)" as AGGREGATOR {
[FedAvgAggregationService\n(pipeline: validate→select→quorum→weights→combine)] as FAAS
[AggregationStrategyFactory\n(fromId — resolves by canonical ID)] as ASF
[AggregationStrategyCatalog\n(all · find · isNative)] as ASC
[FedAvgAggregationStrategyImpl\n(sample-weighted average)] as FEDAVG
[FedMedianAggregationStrategy\n(coordinate-wise median — Byzantine)] as FEDMED
[TrimmedMeanAggregationStrategy\n(discards extremes — trim fraction)] as TRIMMED
[KrumAggregationStrategy\n(selects by minimum distance)] as KRUM
[FedAdamAggregationStrategy\n(adaptive server-side optimizer)] as FEDADAM
[MqttClientUpdateCollector\n(clearRound after aggregation)] as MUCC
}
package "federated-client (3 classes)" as CLIENT {
[FederatedClientService\n(acceptance · preflight · training · publish)] as FCS
[ClientMlRuntimeSupport\n(runtime validation)] as CMRS
[ClientExecutionResult] as CER
}
package "federated-orchestrator (11 classes)" as ORCHESTRATOR {
[RoundCoordinator\n(startRound · signed RoundConfig)] as RC
[FederatedRoundStrategyFactory] as RSF
[AllAcceptedClientsStrategy] as AAC
[RandomSampledClientsStrategy\n(configurable fraction)] as RSS
[RoundRobinStrategy] as RR
}
package "federated-experiment-sdk (8 classes)" as SDK {
interface "TrainingLocalModel" as TJ
[TrainingContext] as TC
[MlAlgorithmCatalog] as MAC
[ExperimentRuntimePaths] as ERP
}
package "federated-local-cdm (18 classes)" as CDM {
[DataComponent\n(sole authorized access to data)] as DC2
[InMemoryLocalCdmRepository] as ILC
[AuthorizedTrainingViewBuilder\n(filters by DataSchemaSpec)] as ATB
[DataProfileService\n(statistical preflight)] as DPS
[MqttTimeSeriesIngestor\n(subscribe + verify + persist)] as MTSI
[SqliteTimeSeriesStore\n(observations · events · entities — único backend, BL-146)] as CTSS
}
package "federated-common (39 classes)" as COMMON {
[ExperimentContract\n(withStatus · withConsentTermsUri)] as EC
[MqttEnvelope«T»\n(signed · verify)] as ME
interface "MqttGateway\n(publish · subscribe wildcard +)" as MQG
[InMemoryMqttGateway\n(MVP — no TLS)] as IMQ
[HmacSignatureService\n(sign · verify constant-time)] as HSS
[VectorCodec\n(toCsv · fromCsv · L2 norm)] as VC
}
package "federated-chaincode-* (9 classes)" as CHAINCODE {
[ExperimentContractChaincode\n(create · publish · activate · close · revoke · updateDraft)] as ECC
[ClientConsentChaincode\n(accept · reject · revoke)] as CCC
[FederatedExperimentChaincode\n(registerRound · registerUpdate · registerGlobalModel)] as FEC
}
package "federated-artifact-service (3 classes)" as ARTIFACT {
[LocalArtifactExperimentService\n(store · read · resolveSecure)] as LAES
[ArtifactRetentionPolicy\n(enforceRetention · enforceAll — LGPD Art. 15)] as ARP
}
package "federated-simulator (4 classes)" as SIM {
[MqttDatasetReplaySimulator\n(replayAllClients)] as MRS
[HarMqttReplayAdapter\n(UCI HAR → MQTT)] as HAR_A
[EcgMqttReplayAdapter\n(ECG5000 → MQTT)] as ECG_A
}
AWS --> AMS
AWS --> AHL
AAB --> AMS
AAB --> ECF
AAB --> LP
LP --> ILMP
LP --> FCLM
FCLM --> CPS
FCLM --> ECC
FCLM --> CCC
FCLM --> FEC
AMS --> ECC
AMS --> CCC
AMS --> FEC
AMS --> ARP
AEE --> RC
AEE --> FAAS
FAAS --> ASF
ASF --> FEDAVG
ASF --> FEDMED
ASF --> TRIMMED
ASF --> KRUM
ASF --> FEDADAM
ASF --> ASC
FAAS --> MUCC
FAAS --> LAES
FCS --> DC2
FCS --> DPS
DC2 --> ILC
DC2 --> ATB
DC2 --> MTSI
MTSI --> CTSS
MTSI --> MQG
MQG --> IMQ
MQG --> ME
ME --> HSS
SIM --> DC2
SIM --> MQG
@enduml
4. Maven Dependency Graph (ADR-004 applied)¶
Ver código-fonte PlantUML
@startuml "HDT-AF - Maven Dependency Graph (ADR-004)"
!theme plain
skinparam componentStyle uml2
skinparam shadowing false
left to right direction
[federated-common] as COM #146c5d;line:white;text:white
[federated-experiment-sdk] as SDK
[federated-local-cdm] as CDM
[federated-artifact-service] as ART
[chaincode-contract] as CC_CON
[chaincode-consent] as CC_CONS
[chaincode-experiment] as CC_EXP
[federated-client] as CLIENT
[federated-orchestrator] as ORCH
[federated-aggregator] as AGG
[federated-rest-api] as ADMIN #315a9e;line:white;text:white
[federated-simulator] as SIM #667085;line:white;text:white
note bottom of SIM
⚠️ ADR-004: simulator does NOT
depend on admin-api
end note
SDK --> COM
CDM --> COM
ART --> COM
CC_CON --> COM
CC_CONS --> COM
CC_CONS --> CC_CON
CC_EXP --> COM
CLIENT --> COM
CLIENT --> SDK
CLIENT --> CDM
CLIENT --> ART
CLIENT --> CC_CONS
CLIENT --> CC_EXP
ORCH --> COM
ORCH --> CC_CONS
ORCH --> CC_EXP
AGG --> COM
AGG --> ART
AGG --> CC_EXP
ADMIN --> COM
ADMIN --> SDK
ADMIN --> CDM
ADMIN --> ART
ADMIN --> CLIENT
ADMIN --> ORCH
ADMIN --> AGG
SIM --> COM
SIM --> SDK
SIM --> CDM
SIM --> ART
SIM --> CLIENT
SIM --> ORCH
SIM --> AGG
@enduml
ADR-004 Note:
federated-simulatorwas decoupled fromfederated-rest-api, ensuring an acyclic dependency graph.