Ir para o conteúdo

Component Diagrams — HDT-AF

Updated on 2026-06-03 to reflect BL-045 through BL-053 (lifecycle management, LedgerPort, AdminHtmlLayout).


1. General Architectural Diagram

Diagrama PlantUML 1

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

Diagrama PlantUML 2

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

Diagrama PlantUML 3

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)

Diagrama PlantUML 4

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-simulator was decoupled from federated-rest-api, ensuring an acyclic dependency graph.