Ir para o conteúdo

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.

Diagrama PlantUML 1

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.

Diagrama PlantUML 2

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)

Diagrama PlantUML 3

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

Diagrama PlantUML 4

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

Diagrama PlantUML 5

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.

Diagrama PlantUML 6

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)

Diagrama PlantUML 7

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)