System Architecture — HDT-AF¶
Updated on 2026-10-25 to include the Android MDPL federated-training orchestrator. The framework supports JVM/Docker clients and an optional on-device Android execution path; Hyperledger Fabric remains the audit/governance layer.
1. Context Diagram (C4 — Level 1)¶
High-level view: who uses the system and which external systems it integrates with.
Ver código-fonte PlantUML
@startuml "HDT-AF - System Context (C4 Level 1)"
!include <C4/C4_Context>
title HDT-AF — System Context
Person(researcher, "Researcher", "Defines federated experiments, monitors rounds, and evaluates global models via the Web Monitor.")
Person(client_op, "Client Operator", "Manages consent and the local dataset at each federated node.")
Person(auditor, "Auditor", "Verifies evidence, hashes, and the audit trail on the Fabric ledger.")
System(hdt_af, "HDT-AF", "Federated Learning framework for Digital Twins. Coordinates collaborative training without centralizing raw data.")
System_Ext(fabric, "Hyperledger Fabric", "Permissioned ledger. Immutably records contracts, consents, hashes, and global models.")
System_Ext(mqtt_broker, "MQTT 5 Broker", "Federated bus with TLS/mTLS. Carries round configurations, local updates, and the global model. (Production target; MVP uses in-memory.)")
System_Ext(iot_devices, "IoT Devices / Sensors", "Real data sources: smartphones (HAR), ECG, industrial sensors (DT). Publish observations to the iot/clients/+/entities/+/observations topics.")
System_Ext(docker_runtime, "Docker Runtime", "Isolates each federated client in a separate container during local training.")
System_Ext(android_device, "Android Device", "Optional mobile federated client. Shares sensor capture and MQTT transport across consented experiments; runs verified DEX plugins through MDPL.")
Rel(researcher, hdt_af, "Creates experiments, starts rounds, monitors metrics", "HTTPS/8088")
Rel(client_op, hdt_af, "Accepts contract, manages consent", "HTTPS/8088")
Rel(auditor, hdt_af, "Queries evidence and the blockchain explorer", "HTTPS/8088")
Rel(hdt_af, fabric, "Records contracts, consents, hashes, models", "CLI peer / Fabric Gateway SDK")
Rel(hdt_af, mqtt_broker, "Publishes/subscribes: RoundConfig, ClientUpdate, GlobalModel", "MQTT 5 TLS/mTLS")
Rel(hdt_af, docker_runtime, "Launches one container per federated client", "Docker API")
Rel(iot_devices, hdt_af, "Send observations via IoT Adapter → MQTT", "MQTT 5")
Rel(android_device, hdt_af, "Receives round control; sends signed updates and artifact references", "MQTT 5 + HTTPS")
@enduml
2. Container Diagram (C4 — Level 2)¶
Decomposition into containers (processes/services) with their responsibilities and technologies.
Ver código-fonte PlantUML
@startuml "HDT-AF - Containers (C4 Level 2)"
!include <C4/C4_Container>
title HDT-AF — Containers
Person(researcher, "Researcher / Auditor")
Container_Boundary(admin_boundary, "federated-rest-api (port 8088)") {
Container(monitor_web, "Web Monitor", "Java 25, HTTP/HTTPS", "Operational interface: dashboard, lifecycle, rounds, metrics, blockchain explorer, simulation session.")
Container(admin_svc, "AdminMonitoringService", "Java, Stateful", "Registers experiments, rounds, metrics, consents. Implements LedgerPort.")
Container(ledger_port, "LedgerPort / FabricCliLedgerMirror", "Java Interface", "Abstracts ledger operations. InMemoryLedgerPort for tests; FabricCliLedgerMirror for production.")
Container(sim_session, "SimulationSession + SimulationRoundEngine", "Java, In-memory", "Manages a round-based simulation session via the Web Monitor. IoT Adapter cache.")
}
Container_Boundary(simulator_boundary, "federated-simulator") {
Container(har_adapter, "HarMqttReplayAdapter", "Java", "Reads the UCI HAR Dataset and publishes observations to the IoT MQTT topics.")
Container(ecg_adapter, "EcgMqttReplayAdapter", "Java", "Reads ECG5000 and publishes heartbeats as MQTT ObservationMessage.")
}
Container_Boundary(cdm_boundary, "federated-local-cdm") {
Container(data_component, "DataComponent", "Java", "Mandatory data access port. loadLocalCdmRepository() reads timeseries.db directly; MQTT provenance is structural (BL-091) since MqttTimeSeriesIngestor is the only production writer.")
Container(ingestor, "MqttTimeSeriesIngestor", "Java", "Subscribes to IoT topics, validates HMAC signature, and persists to TimeSeriesStore.")
Container(ts_store, "SqliteTimeSeriesStore", "Java", "Only backend since BL-146. Stores time-series observations and events per client/experiment (timeseries.db).")
}
Container_Boundary(orchestrator_boundary, "federated-orchestrator") {
Container(round_coordinator, "RoundCoordinator", "Java", "Selects clients (all_accepted/random_sampled/round_robin), builds a signed RoundConfig, and registers the round on the ledger.")
}
Container_Boundary(aggregator_boundary, "federated-aggregator") {
Container(aggregator, "FedAvgAggregationService", "Java", "Validates updates, applies quorum, runs the strategy (FedAvg/FedMedian/Krum/FedAdam/FedYogi), and publishes GlobalModel.")
Container(update_collector, "MqttClientUpdateCollector", "Java", "Collects ClientUpdateMessage from the MQTT gateway per round.")
}
Container_Boundary(client_boundary, "federated-client (Docker execution)") {
Container(docker_client, "FederatedClientService", "Java, Docker Container", "Runs preflight, TrainingLocalModel, and publishes ClientUpdate. One container per client per round.")
Container(docker_executor, "FederatedDockerClientExecutor", "Java", "Launches Docker containers with MAIN_CLASS, mounts volumes, reads result.properties.")
}
Container_Boundary(android_boundary, "federated-android-client (participant device)") {
Container(android_service, "FederatedMqttService", "Android foreground service", "Subscribes to cross-experiment round filters; routes each experiment/version to an isolated RoundLifecycle and shares MQTT/CDDL sensor capture.")
Container(mdpl_orchestrator, "FederatedMdplOrchestrator", "Android service coordinator", "Prepares one local training engine per experiment/contract version and releases its package registration on consent revocation.")
Container(android_store, "SqliteObservationStore", "Android SQLite", "Scopes retained observations to experiment and contract version; only consented round windows are persisted.")
Container(cddl_local, "CDDL/CDAL local microbroker", "Android libraries", "Collects local sensor readings and transports MDPL requests/results without forwarding training data remotely.")
Container(mdpl_engine, "FederatedMdplInferenceEngineService", "MDPL OnArrival service", "Implements the optional federated-training capability of OnDataArrivalInference and runs the selected experiment DEX plugin.")
Container(package_manager, "MdplClientPackageManager", "DexClassLoader + Ed25519 verifier", "Verifies, loads and caches signed .hdtclient.zip packages by experiment/version.")
}
Container_Boundary(artifact_boundary, "federated-package-experiment-service") {
Container(artifact_svc, "LocalArtifactExperimentService", "Java, Filesystem", "Stores off-chain artifacts: local_update.bin, metrics.json, aggregation_report.json, model.bin. Path traversal prevention.")
Container(retention, "ArtifactRetentionPolicy", "Java", "Deletes artifacts after the contract's validTo (LGPD Art. 15).")
}
Container_Boundary(common_boundary, "federated-common") {
Container(mqtt_gw, "InMemoryMqttGateway / MqttGateway", "Java Interface", "MQTT bus. MVP: in-memory. Production: MQTT 5 broker with TLS/mTLS.")
Container(hmac_svc, "HmacSignatureService", "Java, HMAC-SHA256", "Signs and verifies MQTT envelopes. Pseudonymizes clientId for the Fabric ledger (LGPD).")
}
Container_Ext(fabric_ledger, "Hyperledger Fabric", "Permissioned ledger", "federated-channel, federated-governance-java chaincode.")
Container_Ext(docker_engine, "Docker Engine", "Container Runtime", "Runs isolated federated client containers.")
Container_Ext(remote_mqtt_broker, "MQTT 5 Broker", "TLS/mTLS", "Federated fl/ control and client-update topics.")
Rel(researcher, monitor_web, "HTTP/HTTPS", "8088")
Rel(monitor_web, admin_svc, "Internal Java calls")
Rel(admin_svc, ledger_port, "LedgerPort interface")
Rel(ledger_port, fabric_ledger, "peer chaincode invoke CLI")
Rel(sim_session, har_adapter, "replayAllRound()")
Rel(sim_session, ecg_adapter, "replayAllRound()")
Rel(har_adapter, mqtt_gw, "publish ObservationMessage")
Rel(ecg_adapter, mqtt_gw, "publish ObservationMessage")
Rel(mqtt_gw, ingestor, "deliver iot/clients/+/entities/+/observations")
Rel(ingestor, ts_store, "append()")
Rel(data_component, ts_store, "readAll()")
Rel(data_component, ingestor, "subscribeToMqttSource()")
Rel(round_coordinator, mqtt_gw, "publish RoundConfig signed")
Rel(docker_executor, docker_engine, "docker run")
Rel(docker_client, data_component, "loadLocalCdmRepository() [validates source=mqtt]")
Rel(docker_client, artifact_svc, "store(local_update.bin)")
Rel(docker_client, mqtt_gw, "publish ClientUpdate signed")
Rel(android_service, remote_mqtt_broker, "subscribe all experiment round/config/finalization filters; publish signed updates")
Rel(android_service, admin_svc, "HTTPS discovery, consent and code manifest")
Rel(mdpl_orchestrator, admin_svc, "HTTPS download of the exact client package")
Rel(android_service, artifact_svc, "upload scoped round artifacts")
Rel(android_service, android_store, "persist/read observations for (experimentId, contractVersion)")
Rel(android_service, cddl_local, "shared sensor capture and device-local MDPL request/result topics")
Rel(android_service, mdpl_orchestrator, "prepare or release engine by experiment/contract version")
Rel(mdpl_orchestrator, package_manager, "verify, load and register package")
Rel(mdpl_orchestrator, mdpl_engine, "dispatch federated training through OnDataArrivalInference")
Rel(cddl_local, mdpl_engine, "deliver local OnArrival training request/result")
Rel(update_collector, mqtt_gw, "subscribe fl/experiments/+/rounds/+/clients/+/update")
Rel(aggregator, update_collector, "updatesFor()")
Rel(aggregator, artifact_svc, "store(globalModel, aggregationReport)")
Rel(aggregator, mqtt_gw, "publish GlobalModelPublication")
Rel(aggregator, fabric_ledger, "registerGlobalModelVersion")
@enduml
3. Java Component Diagram (Maven Modules)¶
Ver código-fonte PlantUML
@startuml "HDT-AF - Java Component Diagram (Maven Modules)"
!theme plain
skinparam componentStyle uml2
skinparam packageStyle rectangle
skinparam shadowing false
package "federated-common (39 classes)" as COMMON #146c5d;line:white;text:white {
[ExperimentContract\n(record, withStatus, withConsentTermsUri)] as EC
[MqttEnvelope«T»\n(signed · verify HMAC)] as ME
interface "MqttGateway\n(publish · subscribe wildcard +)" as MQG
[InMemoryMqttGateway\n(MVP — in-memory, no TLS)] as IMQ
[HmacSignatureService\n(sign · verify constant-time)] as HSS
[VectorCodec\n(toCsv · fromCsv · L2 norm)] as VC
[ObservationMessage\nEventMessage] as OBS
[IotTopics\n(entityObservation · entityEvent)] as IotT
}
package "federated-local-cdm (18+ classes)" as CDM {
[DataComponent\n✓ loadLocalCdmRepository()\n✓ awaitMqttDataAndMaterialize()] as DC
[MqttTimeSeriesIngestor\n(subscribe · verify · persist)] as MTSI
[SqliteTimeSeriesStore\n(timeseries.db — único backend, BL-146)] as SQLite
[AuthorizedTrainingViewBuilder\n(empty allowedCodes = allow all)] as ATB
[DataProfileService\n(preflight: MIN_SAMPLES, MIN_POSITIVES…)] as DPS
}
package "federated-experiment-sdk (8 classes)" as SDK {
interface "TrainingLocalModel\n(algorithmSpec · execute)" as TLM
[TrainingContext\n(authorizedDataView · hyperparameters · globalModel)] as TC
[ExperimentRuntimePaths\n(dataRoot · artifactRoot via env vars)] as ERP
[MlAlgorithmCatalog\n(FEDERATED_MLP_CLASSIFIER · …)] as MAC
}
package "federated-artifact-service (3 classes)" as ART {
[LocalArtifactExperimentService\n(store · resolveSecure — path traversal)] as LAES
[ArtifactRetentionPolicy\n(enforceRetention — LGPD Art. 15)] as ARP
}
package "federated-chaincode-* (3 modules)" as CHAINCODE {
[ExperimentContractChaincode\n(create · publish · activate · close · revoke)] as ECC
[ClientConsentChaincode\n(accept · reject · revoke)] as CCC
[FederatedExperimentChaincode\n(registerRound · registerUpdate · registerGlobalModel)] as FEC
}
package "federated-client (3 classes)" as CLIENT #7c3aed;line:white;text:white {
[FederatedClientService\n(preflight · executeRound · publishUpdate)] as FCS
[FederatedDockerClientExecutor\n(execute — launches Docker containers)\n(isDockerAvailable — test guard)] as FDCE
[ClientMlRuntimeSupport\n(ML target validation)] as CMRS
}
package "federated-orchestrator (5 classes)" as ORCH {
[RoundCoordinator\n(startRound · signed RoundConfig)] as RC
[AllAcceptedClientsStrategy\nRandomSampledClientsStrategy\nRoundRobinStrategy] as Strats
}
package "federated-aggregator (11 classes)" as AGG {
[FedAvgAggregationService\n(validate · select · quorum · combine)] as FAAS
[AggregationStrategyFactory\n(fromId: fedavg/fedmedian/krum/fedadam/fedyogi)] as ASF
[MqttClientUpdateCollector\n(clearRound after aggregation)] as MUCC
}
package "federated-simulator (4 + 3 adapters)" as SIM #667085;line:white;text:white {
[MqttDatasetReplaySimulator\n(replayAllClients)] as MDRS
[HarMqttReplayAdapter\n(UCI HAR → MQTT)\n(featureCodes())] as HAR_A
[EcgMqttReplayAdapter\n(ECG5000 → MQTT)] as ECG_A
[SimulationSession\n(ACTIVE/PAUSED/DONE/ERROR — immutable)] as SimSess
[SimulationRoundEngine\n(adapter cache by type:path:maxClients)] as SimEng
}
package "federated-rest-api (30+ classes)" as ADMIN #315a9e;line:white;text:white {
[AdminWebServer\n(HTTP router — 4,000+ lines)] as AWS
[AdminMonitoringService\n(stateful: experiments · rounds · metrics)] as AMS
[AdminApplicationBootstrap\n(factory: createMonitoringServiceWithPort)] as AAB
interface "LedgerPort\n(12 lifecycle operations)" as LP
[InMemoryLedgerPort\n(idempotent no-op — tests/MEMORY)] as ILMP
[FabricCliLedgerMirror\n(implements LedgerPort+FabricExperimentBridge)] as FCLM
[ClientPseudonymService\n(LGPD — sha256: + 32 hex)] as CPS
[TlsConfig\n(HttpsServer when ADMIN_TLS_KEYSTORE)] as TLS
[AdminHtmlLayout\n(CSS · badge · row · tabs — testable static)] as AHL
}
package "research/experiments" as RESEARCH #b45309;line:white;text:white {
[exp-har-smartphones-001\nHarFederatedExperimentApp\nDockerHarClientApp\nHarTrainingLocalModel] as HAR
[exp-ecg5000-anomaly-001\nEcg5000FederatedExperimentApp\nDockerEcgClientApp\nEcg5000TrainingLocalModel\nDifferentialPrivacy (LGPD)] as ECG
}
' ─── MAIN DEPENDENCIES ───
CDM --> COMMON
SDK --> COMMON
ART --> COMMON
CHAINCODE --> COMMON
CLIENT --> COMMON
CLIENT --> SDK
CLIENT --> CDM
CLIENT --> ART
CLIENT --> CHAINCODE
ORCH --> COMMON
ORCH --> CHAINCODE
AGG --> COMMON
AGG --> ART
AGG --> CHAINCODE
SIM --> COMMON
SIM --> SDK
SIM --> CDM
SIM --> ART
ADMIN --> COMMON
ADMIN --> SDK
ADMIN --> CDM
ADMIN --> ART
ADMIN --> CLIENT
ADMIN --> ORCH
ADMIN --> AGG
RESEARCH --> CLIENT
RESEARCH --> ORCH
RESEARCH --> AGG
RESEARCH --> ADMIN
RESEARCH --> SIM
@enduml
4. Data Pipeline — Mandatory MQTT¶
Ver código-fonte PlantUML
@startuml "HDT-AF - Data Pipeline (Mandatory MQTT)"
!theme plain
skinparam componentStyle uml2
skinparam packageStyle rectangle
skinparam shadowing false
left to right direction
package "Data Sources" as SOURCE {
[UCI HAR Dataset\n(features.txt + X_train.txt)] as UCI
[ECG5000\n(ECG5000_TRAIN.arff/.txt)] as ECG5K
}
package "IoT Adapters (federated-simulator)" as ADAPTERS {
[HarMqttReplayAdapter\n.replayAll()] as HAR_A
[EcgMqttReplayAdapter\n.replayAll()] as ECG_A
}
package "MQTT Bus" as MQTT_BUS {
[iot/clients/{id}/entities/{e}/observations\niot/clients/{id}/entities/{e}/events] as TOPICS
[MqttEnvelope.signed()\nHMAC-SHA256 verified at the receiver] as MQTT_SIGN
}
package "Ingestion (federated-local-cdm)" as INGESTION {
[MqttTimeSeriesIngestor\n(subscribe · verify · append)] as INGESTOR
[SqliteTimeSeriesStore\ntimeseries.db — único backend, BL-146] as STORE
}
package "Materialization" as MATERIALIZATION {
[DataComponent\n.loadLocalCdmRepository()\n(lê direto de timeseries.db)] as DC
[Proveniência estrutural (BL-091):\núnico escritor de produção é\nMqttTimeSeriesIngestor — sem\nchecagem em runtime] as META #16a34a;line:white;text:white
}
package "Training (Docker)" as DOCKER_TRAINING {
[AuthorizedTrainingViewBuilder\n(empty allowedCodes = allow all)] as VIEW
[DataProfileService\n(preflight: MIN_SAMPLES, completeness…)] as PREFLIGHT
[TrainingLocalModel.execute()\n(HarTrainingLocalModel / Ecg5000TrainingLocalModel)] as TLM
[DifferentialPrivacy\n(L2 clip + Gaussian noise — mandatory for ECG)] as DP #7c3aed;line:white;text:white
[local_update.bin\nmetrics.json\ndata_profile.json] as RESULT
}
UCI --> HAR_A
ECG5K --> ECG_A
HAR_A --> TOPICS
ECG_A --> TOPICS
TOPICS --> MQTT_SIGN
MQTT_SIGN --> INGESTOR
INGESTOR --> STORE
STORE --> DC
DC --> META
META --> VIEW
VIEW --> PREFLIGHT
PREFLIGHT --> TLM
TLM --> DP
DP --> RESULT
@enduml
5. Audit Flow — Hyperledger Fabric¶
Ver código-fonte PlantUML
@startuml "HDT-AF - Audit Flow (Hyperledger Fabric)"
!theme plain
skinparam componentStyle uml2
skinparam packageStyle rectangle
skinparam shadowing false
package "Main Process (JVM)" as MAIN {
[ExperimentContract\n(DRAFT → PUBLISHED → ACTIVE → CLOSED)] as CONTRACT
[ClientConsentChaincode\n(accept · reject · revoke)] as CONSENT
[FederatedExperimentChaincode\n(registerTrainingRound)] as ROUND
[registerLocalUpdateHash\n(pseudonymized clientId)] as UPDATE
[registerAggregationHash\nregisterGlobalModelVersion] as AGGR
}
package "LGPD Controls" as LGPD {
[ClientPseudonymService\nsha256: + 32 hex\n(LGPD Art. 13)] as PSEUDO #f59e0b;line:white;text:white
[ArtifactRetentionPolicy\n(deletes after validTo)\n(LGPD Art. 15)] as RETENTION #ef4444;line:white;text:white
[DifferentialPrivacy\n(L2 clip + Gaussian)\n(LGPD Art. 46 — sensitive data)] as DP_LGPD #7c3aed;line:white;text:white
[TlsConfig\nHTTPS/8088\n(LGPD Art. 46)] as TLS_MON
}
package "Hyperledger Fabric — federated-channel" as FABRIC {
[federated-governance-java Chaincode] as CC
[World State\nExperimentContractAsset\nClientConsentAsset\nTrainingRoundAsset\nAuditEventAsset\nGlobalModelAsset] as WS
[Immutable Ledger\n(hash + URI + version)] as IMMUT #146c5d;line:white;text:white
}
package "Off-chain (target/artifacts)" as OFF_CHAIN {
[local_update.bin\nmetrics.json\naggregation_report.json\nmodel.bin] as ARTEFACTS
}
CONTRACT --> PSEUDO
CONSENT --> PSEUDO
ROUND --> PSEUDO
UPDATE --> PSEUDO
PSEUDO --> CC
AGGR --> CC
CC --> WS
WS --> IMMUT
ARTEFACTS --> CC : hash + URI recorded on-chain
RETENTION --> ARTEFACTS : deletes expired artifacts
DP_LGPD --> UPDATE : applies before publishing update
TLS_MON --> CONTRACT : protects data in transit
@enduml
6. Docker Deployment Path (Docker + Fabric)¶
6.1 Local Development Path (JVM / Single Host)¶
This deployment view covers the JVM/Docker client path on a local developer machine. The separate Android deployment
uses the installed app plus an optional signed .hdtclient.zip and runs training on-device through
MDPL; see the federated client component
and sequence diagram 9.
Ver código-fonte PlantUML
@startuml "HDT-AF - Deployment Architecture (Docker + Fabric)"
!theme plain
skinparam componentStyle uml2
skinparam packageStyle rectangle
skinparam shadowing false
package "Host — Researcher (macOS/Linux)" as HOST {
[🖥️ Web Monitor\nhttp://localhost:8088\n(federated-rest-api)] as MONITOR #315a9e;line:white;text:white
[scripts/\nrun-simulator.sh\nrun-har-experiment.sh\nrun-ecg-experiment.sh] as SCRIPTS
[target/artifacts/\n(off-chain artifacts)] as ARTIFACTS
[data/{clientId}/{expId}/\ndataset.csv (source=mqtt)\nmetadata.json] as DATA
[observations_ts.csv\nevents_ts.csv] as TS_FILES
[target/classes/\n(compiled bytecode)] as CLASSES
}
package "Docker Containers — Isolated Training" as DOCKER_CLIENTS {
[🐳 hdt-af-client:local\nclient-1\nMAIN_CLASS=DockerHarClientApp\n/app/data/1/exp-har:ro\n/app/artifacts:rw] as C1 #7c3aed;line:white;text:white
[🐳 hdt-af-client:local\nclient-2\n/app/data/2/exp-har:ro] as C2 #7c3aed;line:white;text:white
[🐳 hdt-af-client:local\nclient-N\n/app/data/N/exp-har:ro] as CN #7c3aed;line:white;text:white
}
package "Hyperledger Fabric — test-network" as FABRIC_NETWORK {
[peer0.org1\n(Org1)] as PEER0ORG1
[peer0.org2\n(Org2)] as PEER0ORG2
[orderer.example.com] as ORDERER
[federated-channel\nchaincode: federated-governance\nv1.0.0] as CHANNEL #146c5d;line:white;text:white
}
MONITOR --> PEER0ORG1 : FabricCliLedgerMirror\nLEDGER_MODE=blockchain (unico modo)
PEER0ORG1 --> CHANNEL
PEER0ORG2 --> CHANNEL
CHANNEL --> ORDERER
SCRIPTS --> DATA : Starts JVM\nMQTT replay → materialize
DATA --> C1 : volume :ro
DATA --> C2 : volume :ro
DATA --> CN : volume :ro
CLASSES --> C1 : volume :ro
CLASSES --> C2 : volume :ro
CLASSES --> CN : volume :ro
ARTIFACTS --> C1 : volume :rw
ARTIFACTS --> C2 : volume :rw
ARTIFACTS --> CN : volume :rw
C1 --> ARTIFACTS : result.properties\n(ClientUpdate)
C2 --> ARTIFACTS : result.properties\n(ClientUpdate)
CN --> ARTIFACTS : result.properties\n(ClientUpdate)
TS_FILES --> DATA : feeds materializeDatasetFromStore()
@enduml
6.2 Remote VM Deployment Stack (192.168.10.198 · Multi-Service Docker Compose)¶
In a server/VM deployment (Debian Linux x86_64, host 192.168.10.198), the full HDT-AF platform runs containerized under Docker Compose (docker/docker-compose.vm.yml), utilizing dual-network bridging:
- hdt-net: Bridge network connecting hdt-af-admin (:8088), mosquitto (:1883, :8883 TLS, :9001 WS), and postgres (:15432 mapped to avoid collision with port 5432).
- fabric_test: External bridge network linking hdt-af-admin directly to Hyperledger Fabric peers (peer0.org1.example.com:7051, peer0.org2.example.com:9051) and orderer (orderer.example.com:7050) using native Docker DNS without /etc/hosts modifications.
For the comprehensive deployment diagrams (PlantUML + Mermaid) and sequence flows, see 05-vm-deployment-topology.md and the operational guide in vm-deployment-guide.md.
7. Maven Dependency Graph (ADR-004)¶
Ver código-fonte PlantUML
@startuml "HDT-AF - Maven Dependency Graph (ADR-004, with tests)"
!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 #7c3aed;line:white;text:white
[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
[federated-system-tests] as TEST #b45309;line:white;text:white
note bottom of SIM
⚠️ ADR-004: simulator does NOT
depend on admin-api
(acyclic graph)
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
TEST --> COM
TEST --> SDK
TEST --> CDM
TEST --> CLIENT
TEST --> ORCH
TEST --> AGG
TEST --> ADMIN
TEST --> SIM
@enduml
Architectural Decisions Legend¶
| ADR | Title | Impact |
|---|---|---|
| ADR-001 | AdminHtmlLayout extracts static CSS/helpers from AdminWebServer |
Layout testability without a server |
| ADR-003 | LedgerPort interface decouples AdminMonitoringService from Fabric |
InMemoryLedgerPort for tests, FabricCliLedgerMirror for production |
| ADR-004 | federated-simulator does not depend on federated-rest-api |
Acyclic Maven dependency graph |
| MQTT-001 | Mandatory MQTT pipeline for training data | Guaranteed structurally since BL-091 (not by a runtime check): MqttTimeSeriesIngestor is the only production writer of timeseries.db, so presence of data already proves MQTT provenance — the earlier requireMqttProvenance()/source=mqtt runtime check was removed as redundant |
| DOCKER-001 | Admin-monitor JVM clients run exclusively in Docker containers | Isolates that execution path; does not describe the separate Android mobile client |
| LGPD-001 | clientId pseudonymized before any on-chain write |
sha256: + 32 hex via ClientPseudonymService (LGPD Art. 13) |
| LGPD-002 | ArtifactRetentionPolicy deletes artifacts after validTo |
Compliance with LGPD Art. 15 |
| LGPD-003 | Mandatory DP-SGD in the ECG5000 experiment | Sensitive health data (LGPD Art. 5, II + Art. 46) |