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.mdedocs/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)¶
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¶
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¶
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¶
- Transporte externo único em MQTT 5 (
BL-259): Ingestão (iot/emhub/) e protocolo federado (fl/) usamPahoMqttGatewaysobre TLS 1.3/mTLS (:8883). O salto HTTP+SSE (EmbeddedRestSseBroker+RestSseGateway) é restrito à comunicação interna do Gêmeo Digital Local (BL-243). - 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. - Governança obrigatória em
BLOCKCHAIN(BL-233): ApenasLedgerMode.BLOCKCHAINé suportado em produção; o monitor utilizaFabricGatewayLedgerMirrorvia Fabric Gateway SDK. - Soberania local de dados & LGPD: Dados brutos permanecem no SQLite do cliente (
DataComponent). Pseudonimização SHA-256 (ClientPseudonymService) protegeclientIdon-chain e a Privacidade Diferencial é aplicada centralmente porDataComponenta partir deresearch.xml. - Isolamento de execução de experimentos (
BL-236) e endurecimento web (BL-334): Pacotes.hdtpkg.zipimplantados executam em subprocesso OS dedicado (IsolatedExperimentRunnerApp), eAdminWebServerprotege o pool HTTP (>= 64threads), limita conexões SSE (24), isola locks de criação de sessão por experimento e retorna HTTP202após15sem 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)