Ir para o conteúdo

Arquitetura do Sistema — HDT-AF

O HDT-AF (Human Digital Twin — Autonomous Federated Learning Framework) é uma plataforma Java 25 para aprendizado federado consciente de privacidade aplicada a Gêmeos Digitais Humanos e Industriais. A arquitetura combina contratos versionados de experimento, acesso controlado aos dados locais via DataComponent, treinamento em contêineres Docker ou dispositivos Android (MDPL/CDDL), barramento MQTT 5 com TLS/mTLS e governança/auditoria imutável em Hyperledger Fabric.

Para detalhes específicos de diagramas C4, UML 2.5 e fluxos operacionais, consulte também docs/diagrams/README.md e docs/modules.md.


1. Visão Macro e Subsistemas

Subsistema Módulos principais Responsabilidade
Governança e Auditoria federated-chaincode, deploy/fabric/chaincode/federated-governance-java Smart contracts Java para ciclo de contrato (ExperimentContractChaincode), consentimento LGPD (ClientConsentChaincode), evidências de rodada/modelo e pacotes de inferência (FederatedExperimentChaincode).
Controle Administrativo e Monitoramento federated-rest-api, federated-package-experiment-service, federated-admin-web API REST OpenAPI 3.1 (:8088), interface HTML servida pelo AdminWebServer, SSE em tempo real, empacotamento/deploy isolado (IsolatedExperimentRunnerApp), gestão de contêineres Docker e integração Fabric Gateway.
Orquestração e Agregação federated-orchestrator, federated-aggregator, federated-model-inference Seleção de clientes, emissão de RoundConfig e RoundFinalizationSignal, relay obrigatório (ClientUpdateRelay), resolução de artefatos, agregação (FedAvg, FedMedian, TrimmedMean, Krum, MultiKrum, FedAdam, FedYogi), publicação de modelo global e serviço HTTP de inferência (:8092).
Comunicação e Simulação federated-common, federated-containers, federated-simulator Contratos de domínio, criptografia X.509/HMAC, MqttEnvelope<T>, cliente Paho MQTT 5 TLS 1.3/mTLS (:8883), replay IoT/CDDL e pacotes de simulação .hdtsim.zip.
Nó Participante (JVM/Docker & Android) federated-client, federated-local-cdm, federated-digital-twin-broker, federated-experiment-sdk, federated-experiment-packager, federated-android-client DataComponent, SQLite local (timeseries.db e model_artifacts.db), preflight estatístico, Privacidade Diferencial centralizada, broker interno HTTP+SSE do gêmeo digital local (EmbeddedRestSseBroker), validação local pré-promoção e runtime Android MDPL/CDDL.

2. Diagrama de Componentes (PlantUML)

Diagrama PlantUML 1

Ver código-fonte PlantUML
    @startuml "HDT-AF - Macro Component Architecture"
    skinparam shadowing false
    skinparam componentStyle uml2

    package "Plano Administrativo e Governança" {
      [AdminWebServer :8088\n(federated-rest-api)] as Admin
      [IsolatedExperimentRunnerApp\n(Subprocesso OS)] as Isolated
      [Package Experiment Service\n(Staging / Retenção)] as Artifacts
      [Model Inference API :8092\n(federated-model-inference)] as Inference
      database "Hyperledger Fabric\n(federated-governance v1.1)" as Fabric
      database "MongoDB Archive\n(Opt-in #)" as Mongo
    }

    package "Plano Federado e Orquestração" {
      [federated-orchestrator\n(RoundCoordinator, Relay, Collector)] as Orch
      [federated-aggregator\n(FedAvg/Median/Trimmed/Krum/Adam/Yogi)] as Agg
      [Mosquitto MQTT 5\n(TLS 1.3 / mTLS :8883)] as MQTT
    }

    package "Nó Participante / Gêmeo Digital Local" {
      [federated-client / Android MDPL\n(Treino Local + Preflight + DP)] as Client
      [federated-digital-twin-broker\n(DigitalTwinBridge + EmbeddedRestSseBroker)] as TwinBroker
      [DataComponent\n(federated-local-cdm)] as DataComp
      database "SQLite Local\n(timeseries.db / model_artifacts.db)" as SQLite
    }

    Admin --> Fabric : Fabric Gateway SDK (gRPC/TLS :7051)
    Admin --> Isolated : Stdin/Stdout JSON
    Admin --> MQTT : Paho MQTT 5 (:8883)
    Admin --> Mongo : Arquivo opt-in (#)
    Admin --> Artifacts : Armazenamento staging
    Inference --> Fabric : Store/Eval pacotes .hdtmodel.zip
    Orch --> MQTT : RoundConfig / Finalization / GlobalModel
    Orch --> Agg : Aggregate (in-process ou HTTP :9090)
    Orch --> Artifacts : Resolve updates / grava modelo global
    MQTT --> TwinBroker : Envelopes assinados (X.509/HMAC)
    TwinBroker --> Client : Salto interno HTTP+SSE (loopback)
    Client --> DataComp : Visão autorizada + DP centralizada
    DataComp --> SQLite : Leitura/escrita JDBC persistente
    @enduml

3. Fluxos Principais de Dados (PlantUML)

3.1 Ingestão MQTT e Ciclo de Rodada Federada

Diagrama PlantUML 2

Ver código-fonte PlantUML
    @startuml "HDT-AF - End-to-End Federated Round Flow"
    actor Pesquisador as Res
    participant "AdminWebServer\n(:8088)" as Admin
    participant "Hyperledger Fabric" as Fabric
    participant "RoundCoordinator /\nClientUpdateRelay" as Orch
    participant "Mosquitto MQTT 5\n(:8883)" as MQTT
    participant "Participante\n(Client + DataComponent)" as Client
    participant "FedAvgAggregationService" as Agg

    Res -> Admin : Cria/Publica/Ativa Contrato
    Admin -> Fabric : ExperimentContractSmartContract (DRAFT -> ACTIVE)

    MQTT -> Client : Observações IoT/CDDL (mhub/{id}/service_topic/...)
    Client -> Client : Persiste em SQLite local (timeseries.db)

    Res -> Admin : Inicia Rodada
    Admin -> Orch : Dispara execução (assíncrona após 15s / HTTP 202)
    Orch -> Fabric : registerTrainingRound
    Orch -> MQTT : MqttEnvelope<RoundConfig> (fl/.../config)
    Orch -> MQTT : MqttEnvelope<RoundFinalizationSignal> (fl/.../finalization)

    Client -> Client : Verifica contrato, consentimento, algoritmo,\nruntime, preflight e aplica DP via DataComponent
    Client -> Admin : Upload artefatos (REST /artifacts) ou TwinArtifactChannel
    Client -> MQTT : MqttEnvelope<ClientUpdateMessage> (fl/.../updates)
    MQTT -> Orch : ClientUpdateRelay consome client-facing
    Orch -> MQTT : Republica envelope intacto em aggregator-facing

    MQTT -> Orch : MqttClientUpdateCollector.awaitAndResolveUpdates
    Orch -> Agg : aggregate(contract, roundConfig, resolvedUpdates)
    Agg --> Orch : AggregationReport
    Orch -> Fabric : registerAggregationHash + registerGlobalModelVersion
    Orch -> MQTT : MqttEnvelope<GlobalModelPublication> + GlobalModelPayload
    @enduml

3.2 Fluxo de Decisão e Validação Local do Gêmeo Digital

Diagrama PlantUML 3

Ver código-fonte PlantUML
    @startuml "HDT-AF - Local Digital Twin Validation Flow"
    participant "Mosquitto MQTT 5" as MQTT
    participant "DigitalTwinBridge\n(EnvelopeBoundaryGuard)" as Bridge
    participant "EmbeddedRestSseBroker\n(HTTP+SSE Loopback)" as Internal
    participant "DigitalTwinValidatorAdapter" as Validator
    participant "TwinValidationDecisionIngestor\n(Orchestrator)" as Ingestor
    participant "Hyperledger Fabric" as Fabric

    MQTT -> Bridge : MqttEnvelope<GlobalModelPublication>
    Bridge -> Bridge : verify() + verifyPayloadIntegrity()
    Bridge -> Internal : Republica no barramento interno
    Internal -> Validator : Entrega GlobalModelPublication
    Validator -> Validator : LocalModelValidator -> PROMOTE | REJECT | DEFER
    Validator -> Internal : Publica TwinValidationDecisionMessage
    Internal -> Bridge : Encaminha para borda externa
    Bridge -> MQTT : Publica decisão assinada (fl/.../twin/decision)
    MQTT -> Ingestor : Consome e verifica envelope
    Ingestor -> Fabric : registerTwinValidationDecision
    @enduml

4. Decisões Arquiteturais e Invariantes

  1. Transporte externo único em MQTT 5 (BL-259): Ingestão (iot/ e mhub/) e protocolo federado (fl/) usam PahoMqttGateway sobre TLS 1.3/mTLS (:8883). O salto HTTP+SSE (EmbeddedRestSseBroker + RestSseGateway) é restrito à comunicação interna do Gêmeo Digital Local (BL-243).
  2. Isolamento de updates via ClientUpdateRelay (BL-242): Clientes nunca publicam diretamente no tópico consumido pelo coletor/agregador; o orquestrador faz o relay preservando a assinatura original.
  3. Governança obrigatória em BLOCKCHAIN (BL-233): Apenas LedgerMode.BLOCKCHAIN é suportado em produção; o monitor utiliza FabricGatewayLedgerMirror via Fabric Gateway SDK.
  4. Soberania local de dados & LGPD: Dados brutos permanecem no SQLite do cliente (DataComponent). Pseudonimização SHA-256 (ClientPseudonymService) protege clientId on-chain e a Privacidade Diferencial é aplicada centralmente por DataComponent a partir de research.xml.
  5. Isolamento de execução de experimentos (BL-236) e endurecimento web (BL-334): Pacotes .hdtpkg.zip implantados executam em subprocesso OS dedicado (IsolatedExperimentRunnerApp), e AdminWebServer protege o pool HTTP (>= 64 threads), limita conexões SSE (24), isola locks de criação de sessão por experimento e retorna HTTP 202 após 15s em execuções de rodada.

5. Estrutura de Diretórios

projeto_hdt_af/
├── pom.xml                       # Reator Maven raiz (Java 25, 22 módulos ativos)
├── modules/                      # Repositórios Git independentes (ignorados pelo Git raiz)
│   ├── federated-common/         # Modelos, contratos, MQTT, crypto, codecs, ZIP
│   ├── federated-experiment-sdk/ # SDK de extensão de experimentos e runtime paths
│   ├── federated-experiment-packager/ # CLIs/codecs para .hdtpkg.zip, .hdtsim.zip, .hdtclient.zip
│   ├── federated-local-cdm/      # DataComponent, SQLite TimeSeries/ModelArtifactStore, preflight, DP
│   ├── federated-chaincode/      # Simuladores em memória + FabricExperimentBridge
│   ├── federated-package-experiment-service/ # Staging de artefatos e política de retenção
│   ├── federated-model-inference/# Empacotamento .hdtmodel.zip e API HTTP de inferência (:8092)
│   ├── federated-client/         # Cliente federado JVM/Docker + núcleo portável Android/MDPL
│   ├── federated-orchestrator/   # Coordenação de rodadas, estratégias, relay, coletor e publisher
│   ├── federated-aggregator/     # Estratégias de agregação e validação de quórum
│   ├── federated-containers/     # PahoMqttGateway MQTT 5 + TLS/mTLS
│   ├── federated-digital-twin-broker/ # EmbeddedRestSseBroker, bridge e validadores locais
│   ├── federated-rest-api/       # AdminWebServer (:8088), OpenAPI, Fabric Gateway, Docker launcher
│   ├── federated-simulator/      # Replay MQTT e engine de pacotes de simulação CSV
│   ├── federated-system-tests/   # Suítes integradas (unit, integration, e2e)
│   ├── federated-android-client/ # App Android Gradle (:core, :app, :client-engine-plugin)
│   ├── federated-admin-web/      # Frontend React/Vite (SPA desativada no roteamento padrão)
│   ├── federated-docs/           # Portal oficial Read the Docs (MkDocs Material)
│   └── scripts/                  # 21 scripts operacionais (link simbólico scripts/ na raiz)
├── research/                     # 6 módulos de experimento e configurações de datasets
├── deploy/                       # Chaincode Fabric real (Gradle/Java 25), TLS e scripts de rede
├── docker/                       # Dockerfiles, Mosquitto config, Compose VM e observabilidade
├── docs/                         # Documentação técnica canônica e especificações OpenAPI
└── schemas/                      # JSON Schemas (envelope MQTT e manifesto de experimento)