Ir para o conteúdo

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)

Diagrama PlantUML 1

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).