Ir para o conteúdo

Component: Admin API and Web Monitor

Responsibility

The Admin API and the Web Monitor are the operational interface of the system. They allow researchers, auditors, and operators to track contracts, consents, rounds, federated metrics, the task plan, per-round performance, global model history, ledger assets, per-client convergence, and Docker container state.


Implementation

Item Value
Modules modules/federated-rest-api (Java API + HTML rendering engine)
Java package br.ufma.lsdi.admin
Executable application br.ufma.lsdi.admin.AdminWebApp
Script scripts/run-admin-web.sh
Fixed port 8088

How to run

# BLOCKCHAIN is the only supported mode; Fabric credentials and network must be available.
sh scripts/run-admin-web.sh

FEDERATED_LEDGER_MODE=blockchain sh scripts/run-admin-web.sh

Legacy launcher values such as memory and hybrid are normalized to blockchain; they do not enable an in-memory or failure-tolerant ledger mode.

If port 8088 is already in use, the script automatically terminates the previous process (using lsof).

Access at: http://localhost:8088 (plain HTTP) or https://localhost:8088 (with TLS enabled).

HTTPS / TLS (LGPD Art. 46)

The monitor exposes data subject information (consents, individual metrics). TLS is mandatory for LGPD (Brazilian General Data Protection Law) compliance. Configure it before starting:

# Generate a self-signed certificate (development)
keytool -genkeypair -alias admin -keyalg RSA -keysize 2048 -validity 365 \
  -keystore deploy/tls/admin-keystore.p12 -storetype PKCS12 \
  -storepass changeit -keypass changeit \
  -dname "CN=localhost,OU=HDT-AF,O=UFMA,C=BR"

export ADMIN_TLS_KEYSTORE=deploy/tls/admin-keystore.p12
export ADMIN_TLS_PASSWORD=changeit
sh scripts/run-admin-web.sh
Variable Description
ADMIN_TLS_KEYSTORE Path to the PKCS12 or JKS keystore
ADMIN_TLS_PASSWORD Keystore password
ADMIN_TLS_DISABLED=true Disables TLS (development only)

Without ADMIN_TLS_KEYSTORE, the monitor starts over HTTP. Enable HTTPS when the monitor handles personal data outside a trusted local development environment. See the privacy rules in 03-hyperledger-fabric.md and 06-federated-client.md.

The monitor auto-refreshes every 30 seconds on the dashboard and experiment detail pages, showing the updated state without needing to manually reload.


Route map

HTML routes (web interface)

Method Route Screen displayed
GET / Dashboard — overview of all experiments
GET /health Health check — reports ledger mode and Fabric state; blockchain is the only supported mode
GET /openapi.json OpenAPI 3.1 summary in JSON
GET /openapi.yaml Full OpenAPI 3.1 specification, bundled with the application
GET /swagger-ui/ Swagger UI console for documentation and interactive execution of REST operations
GET /experiments/{id} Experiment details, rounds, and consents
GET /experiments/{id}/tasks Task plan (compute plan)
GET /experiments/{id}/performances Series of per-round/worker performance
GET /experiments/{id}/models Global model history and download of each version's vector
GET /experiments/{id}/assets Assets on the Hyperledger ledger
GET /experiments/{id}/rounds/{roundId} Details of a specific round
GET /experiments/{id}/clients Clients page: consent, dataset evidence, and participation
GET /experiments/{id}/blockchain Blockchain Explorer: all assets by type and audit events
GET /experiments/{id}/config Simulation configuration editor (editable hyperparameters)
GET /experiments/deploy Upload form for an ExperimentPackage package (ADR-005)
POST /experiments/deploy Receives the zip via multipart, deploys it, and redirects to the created experiment
POST /experiments/{id}/start Starts a new round (triggers the executor)
POST /experiments/{id}/pause Pauses the experiment
POST /experiments/{id}/run-rounds Runs N consecutive rounds (parameters: numRounds, fineTune)
POST /experiments/{id}/reset-session Resets the stateful session of the selected experiment version
POST /experiments/{id}/config Applies configuration edited via the form
POST /experiments/{id}/clients/{clientId}/accept Records client acceptance
POST /experiments/{id}/clients/{clientId}/reject Records client rejection

Simulation Session routes (/sim-session/)

Implemented in BL-053 and BL-054. Allow controlling per-round experiment execution via the browser.

Method Route Action
GET /experiments/{id}/sim-session Current session state (HTML)
POST /experiments/{id}/sim-session/start Starts the session (params: type, path, maxClients, totalRounds)
POST /experiments/{id}/sim-session/send-round Advances one round
POST /experiments/{id}/sim-session/run-all Runs all remaining rounds in sequence
POST /experiments/{id}/sim-session/pause Pauses the session
POST /experiments/{id}/sim-session/resume Resumes a paused session
POST /experiments/{id}/sim-session/stop Ends the session
GET /api/experiments/{id}/sim-session Session state in JSON (200) or 404 if there is no session

Version parameter: all experiment routes accept ?version=1.0.0 to select the contract version. The default is 1.0.0.

JSON routes (programmatic API)

Method Route Return
GET /api/experiments JSON array with all experiments
GET /api/experiments/{id} Contract, consents, and round history
GET /api/experiments/{id}/state Canonical snapshot of contract, lifecycle, clients, rounds, models, tasks, assets, datasets, simulation, and MQTT
GET /api/experiments/{id}/lifecycle Contract status and actions allowed in the current state
GET /api/experiments/{id}/clients Clients, counters, and consent state
GET /api/experiments/{id}/rounds?version=1.0.0 JSON array with all rounds
GET /api/experiments/{id}/performances?version=1.0.0 JSON array with performance points
GET /api/experiments/{id}/models JSON array with global model versions
GET /api/experiments/{id}/sim-session JSON with simulation session state, or 404
GET /api/experiments/{id}/simulation-config JSON with the simulation configuration (data source, hyperparameters)
POST /api/experiments/{id}/simulation-config Saves the simulation configuration (same parameters as the HTML route)
POST /api/experiments/{id}/sim-session/start Starts the simulation session (datasetType, datasetPath, maxClients, totalRounds); does not require a configured MQTT gateway
POST /api/experiments/{id}/sim-session/send-round Advances one round; without an MQTT gateway, degrades gracefully (does not publish, only advances state)
POST /api/experiments/{id}/sim-session/run-all Runs all remaining rounds in sequence; same graceful degradation without MQTT
POST /api/experiments/{id}/sim-session/pause Pauses the session; JSON 404 if there is no active session
POST /api/experiments/{id}/sim-session/resume Resumes a paused session; JSON 404 if there is no active session
POST /api/experiments/{id}/sim-session/stop Ends the session
POST /api/experiments Creates a DRAFT contract (experimentId, objective, coordinatorId, taskType)
POST /api/experiments/{id}/clone Creates an isolated DRAFT copy with the source's code/configuration; accepts experimentId, coordinatorId, objective, and an optional sourceContractVersion
POST /api/experiments/{id}/publish Publishes the contract; also broadcasts ContractPublishedPayload on MQTT (BL-252 — see 02-topics-and-payloads.md)
POST /api/experiments/{id}/activate Activates or resumes the experiment
POST /api/experiments/{id}/pause Pauses the experiment
POST /api/experiments/{id}/close Closes the experiment (optional reason)
POST /api/experiments/{id}/revoke Revokes the experiment (optional reason)
POST /api/experiments/{id}/start Starts a single round
POST /api/experiments/{id}/run-rounds Runs consecutive rounds (numRounds, fineTune)
POST /api/experiments/{id}/reset-session Resets the stateful session, preserving history
POST /api/experiments/{id}/restart Restarts the experiment and removes round history
POST /api/experiments/{id}/update Updates the objective while the contract is in DRAFT
POST /api/experiments/{id}/config Updates the allowed hyperparameters of the simulation configuration
POST /api/experiments/{id}/delete Removes a dynamically deployed experiment, without deleting research/experiments/
POST /api/experiments/{id}/clients/{clientId} Manages a client via action=add|accept|reject|register
POST /api/client-installations Registers the installation's anonymous UUID v4; accepts anonymous_uuid, platform, and app_version, with no hardware IDs or personal data
POST /api/experiments/deploy Deploys an .hdtpkg.zip package via multipart/form-data and returns JSON (201)
POST /api/client-packages/deploy Independently deploys a signed Android .hdtclient.zip; validates Ed25519 trust and experiment/version binding
POST /api/datasets/deploy Deploys an .hdtsim.zip package via multipart/form-data and returns JSON (201)

/api/rounds/publish//api/rounds/events removed (BL-259). BL-241 (Phase 1 of BL-240) had added these as a REST+SSE transport for the round protocol (fl/); that migration was reverted at the user's request and the endpoints, TopicFilteredSseEventBus, and the mTLS client-truststore config scoped to them (ADMIN_TLS_CLIENT_TRUSTSTORE/_PASSWORD in TlsConfig) were removed entirely. The round protocol is MQTT-only again for every composition root — see 06-federated-client.md and 18-rest-sse-gateway.md (historical record).

Mutating operations return JSON with status, experimentId, contractVersion, and command. Open http://localhost:8088/swagger-ui/ to check the parameters and execute them directly from the monitor.

Client-facing routes (called by HDT participants, not the dashboard)

The table above is the "núcleo federado" API — administration/monitoring, used by the dashboard and by operator-driven integrations. A separate subset of the same server is called by the HDT participants themselves (Docker daemons, the Android app) — never by a human operator directly. Full request/response detail is in openapi-hdt-client.yaml; this table is a quick index:

Method Route Purpose
POST /api/experiments/{id}/clients/{clientId}/announce Bridge HTTP→MQTT: a participant with no direct broker access announces its presence
POST /api/experiments/{id}/clients/{clientId}/consent A participant decides its own consent (auto-accept/auto-reject) — converges on the same AdminMonitoringService.acceptClient/rejectClient the dashboard's Accept/Reject buttons use; see the sequence diagram 08-consentimento-usuario.puml
POST /api/experiments/{id}/clients/{clientId}/cddl-status Heartbeat of CDDL/CDAL collection status — metadata only, never a sensor reading
GET /api/cddl-status / /api/experiments/{id}/cddl-status Last heartbeat per participant, across all experiments or scoped to one
GET /api/experiments/{id}/client-package?version={contractVersion} Downloads the independently deployed, signed DEX package for the Android client
POST /api/experiments/{id}/rounds/{roundId}/aggregation-result Legacy callback from the Docker aggregator daemon, for experiments not yet converted to the "aggregator responds directly" pattern (BL-244/BL-250) — exp-ergonomic-risk-001 no longer uses this path

The Android client package is independent of /api/experiments/deploy: it has its own .hdtclient.zip format, deployment route, trusted signing key, storage, and version binding. Configure the server's Ed25519 public key with HDT_AF_CLIENT_PACKAGE_TRUSTED_PUBLIC_KEY and HDT_AF_CLIENT_PACKAGE_TRUSTED_KEY_ID. The Android build pins the corresponding public key; the private signing key is never sent to the server or installed in the app. See component 06.

run-rounds with live Docker participants (BL-200): triggerRoundForExternalParticipants (the call run-rounds/start make when Docker containers are the authoritative participants) never blocks waiting for a real client/aggregator response — it only publishes the round config and returns. Before BL-200, run-rounds's loop fired every one of the numRounds requested back-to-back in milliseconds, long before any of them could possibly have been aggregated (a real incident: exp-ergonomic-risk-002 had 10 rounds fire in a ~30ms burst, all with 0 clients and a corrupted model-version sequence — see BL-200/BL-201 in backlog.md). run-rounds now refuses to trigger a new Docker round while the previous one is still unresolved: it throws IllegalStateException naming the pending round if nothing was executed yet in the call, or stops early and returns the partial count if some rounds already succeeded. Practically: a run-rounds call with Docker participants live and numRounds > 1 will only ever execute 1 new round per call — call it again after that round resolves (visible via GET /api/experiments/{id}/rounds or the round-completed SSE event) to progress further.

Where that logic lives (BL-195/BL-196): the body of triggerRoundForExternalParticipants is no longer written out in each of the 5 *FederatedSession classes. They now delegate to ExternalParticipantRoundTrigger (module federated-orchestrator), which owns the single- publication guard, the startRoundWithHyperparameters/finalizeRound pair and the globalModelVersion advance. Each session supplies only what is genuinely experiment-specific: its hyperparameters, its algorithm selection, and a callback that publishes its own dataset.

Two open BL-196 defects disappear by construction once that state lives in one place: the publish-once guard is now synchronized on the trigger instance instead of a bare boolean whose correctness silently depended on an external ReentrantLock no signature declared; and the dataset counts as published only when the callback reports at least one observation, so a publication that published nothing (e.g. an empty client list) no longer locks the session out of ever publishing again.

Canonical experiment state (BL-111)

GET /api/experiments/{id}/state?version=1.0.0 is the recommended read for a screen or client that needs the full operational state without inferring information from multiple calls. The response includes api_version, generated_at, experiment, lifecycle, clients, rounds, current_round, models, tasks, assets, datasets, simulation, mqtt, and links to specialized routes. The specific routes remain available for filters and write operations.

Each round exposes started_at, deadline, and ended_at. The end timestamp is null while the round is open and is recorded when aggregation registers completion. Instant events remain available at GET /api/events/stream (round-started and round-completed); MQTT remains the channel that authorizes the mobile client to collect, train, and send updates.

The installations endpoint is idempotent and keeps the registry only in memory: it returns 201 the first time and 200 on subsequent last-contact updates. There is no listing endpoint, in order to reduce traceability surface; in production, use the monitor with TLS and edge authentication.


Web interface screens

1. Dashboard (/)

The home screen displays one card per experiment with:

  • Experiment name and objective
  • Contract status badge (ACTIVE, PAUSED, DRAFT, etc.)
  • Quick counters:
  • Accepted — clients with active consent
  • Pending — clients with no decision yet
  • Not accepted — rejected or revoked
  • Rounds — total rounds started
  • Tasks — total tasks in the compute plan
  • Assets — total assets registered on the ledger
  • Action buttons: Details · Tasks · Performances · Models · Hyperledger Assets · Start round · Pause

The dashboard auto-refreshes every 30 seconds.


2. Experiment details (/experiments/{id})

Divided into sections:

2a. Header and contract details

  • Experiment ID, objective, contract version
  • Coordinator, digital twin type, task type, contract hash
  • Buttons: Task plan · Performances · Models · Assets · Start round · Pause

Table with each client and: - Consent status (badge: ACCEPTED / REJECTED / REVOKED / PENDING) - Timestamp of the last update - Action buttons: Accept / Reject (trigger ledger operations)

2c. Rounds table

Each row represents a round with:

Column Description
Round Round number
Status Current status badge
Accepted Number of clients with an accepted update
Tasks Number of tasks in the compute plan
Containers Number of Docker containers (if in Docker mode)
Examples Total number of training samples
Local metric Name and value of the weighted local metric (e.g., train_accuracy=0.8312)
Loss Final local loss weighted by aggregation weights
Global metric Global model metric evaluated on the contractual dataset (e.g., test_accuracy=0.8120)
Trend Visual convergence indicator: ↑ (improving), — (stable), ↓ (worsening)
Average norm Average of the local update norms
Deadline Round deadline
Action Link to the round detail page

2d. Learning metrics per round (timeline)

Set of responsive SVG charts with:

  • Weighted loss — weighted average of the final loss of participating clients;
  • Global metric — global model metric on the contractual test dataset, when defined in the AggregationReport;
  • Weighted local metric — clients' local metric weighted by aggregation weights.

Below, a table with: round · strategy · clients · examples · weighted loss · local metric · global metric · average norm · maximum norm · quorum satisfied.

The ↑/—/↓ trend is calculated by comparing the current round's metric with the previous one. A variation above +0.001 → ↑; below −0.001 → ↓; within the range → —.

This screen auto-refreshes every 30 seconds.


3. Round details (/experiments/{id}/rounds/{roundId})

3a. Round information

  • Global model version for the round
  • Start and deadline timestamps
  • Round configuration hash

3b. Participation

  • Accepted clients (with a valid update)
  • Pending clients (no update in the round)
  • Not-accepted clients (no consent)

3c. Federated learning metrics

Summary cards: - Participating clients — number of updates accepted by the aggregator - Training examples — sum of all clients' samples - Weighted local metric — average weighted by number of samples - Weighted loss — clients' final loss weighted by the FedAvg weights - Global metric — global model metric evaluated on the contractual holdout - Average norm — average of the update norms - Maximum norm — largest norm (reference for outlier detection) - Global model — version and abbreviated hash of the candidate model

Below, a per-client table with: - Update status (badge) - Samples, positives, FedAvg weight - Update norm - Actual local metric (e.g., train_accuracy=0.8312) - Preflight failure diagnostics (failed checks)

3d. Local convergence per client

Section displayed when per-epoch training data is available (HAR experiment and others that propagate trainingHistory and perClassAccuracy).

For each client:

Epoch table: | Epoch | Loss | Accuracy | Grad. norm | |---|---|---|---| | 1 | 1.7423 | 0.3821 | 0.021345 | | 2 | 1.4122 | 0.5134 | 0.018902 | | ... | ... | ... | ... |

Per-class accuracy chart (HAR): Horizontal bars for each activity (WALKING, SITTING, STANDING, etc.) with a visual percentage. Allows identification of misclassified classes per client.

This section is essential for detecting client drift: clients whose data patterns are very different from the rest tend to show convergence curves and per-class accuracy that diverge from the others.

3e. Docker containers

Table displayed when the round was executed with FEDERATED_CLIENT_EXECUTION_MODE=docker: - Client, container name and ID - Docker image used - Status and exit code - Result path - Summarized log (no raw data)

DockerParticipantLaunchService — two query paths, deliberately

The launcher exposes two ways to ask about containers, and picking the wrong one is a performance bug, not a style preference:

Method Docker calls Use for
listParticipants(experimentId) 1 docker ps + 3 per container (2 × inspect, 1 × logs --tail 20) the containers tab and the JSON API, which display image, exit code, timestamps and logs
activeClientParticipantIds(experimentId) exactly 1 docker ps, filters applied by Docker the per-round guard

Fixed defect (BL-208). activeClientParticipantIds used to be built on listParticipants. It sits on the hot path — AdminMonitoringService.setDockerParticipantsLiveCheck consults it on every round to decide whether execution goes to the Docker participants or the in-memory session — so with 5 clients plus the aggregator it spawned 19 subprocesses, each with a 60 s timeout, only to answer "is any client running?". The same pathology BL-140 fixed for docker info, at 19× the scale: a degraded Docker daemon stalled every round for minutes.

It now issues a single docker ps with label=…experiment, label=…role=client and status=running, letting Docker do the filtering. The participantId is derived from the container name instead of a docker inspect of the environment: containerName() is deterministic and its sanitisation is per-character, so the prefix generated with an empty participantId is exactly the prefix of the real names.

Container logs now reach the host (BL-231)

createParticipant mounts logs/docker/{experimentId}/{role}/{participantId}:/app/logs on every docker run -d, for both Role.CLIENT and Role.AGGREGATOR — unconditional, unlike the /app/data mount below it, which only applies to clients. Without it, the container's Logback writes to /app/logs, which resolves relative to WORKDIR /app (docker/client/Dockerfile) and is never visible on the host — the same gap fixed for the ephemeral one-shot clients in 06-federated-client.md. One directory per participant (not a single shared folder) keeps the aggregator and every client writing to their own hdt-af.log/hdt-af-error.log, since these are persistent containers that can run concurrently for the whole experiment lifetime. Not pre-created in Java — same reasoning already applied to clientDataDirectory: Docker creates the bind-mount source directory when needed, which keeps createParticipant testable with synthetic projectRoot paths that don't exist on disk.

Training data and model exposed under logs/ too (BL-232)

Right after a CLIENT container is created successfully, createParticipant also creates logs/<containerName>/data (symlink to clientDataDirectory — the persistent SQLite populated by DataComponent over MQTT) and logs/<containerName>/model (symlink to target/artifacts/{experimentId}/{participantId}, the parent of every round-N this client has produced — unlike the ephemeral executor's version in 06-federated-client.md, which points at a single round's directory, this container is persistent and lives across the whole experiment, so the link covers all rounds at once). AGGREGATOR containers get neither — the aggregator doesn't train.

Best-effort, same philosophy as destroyParticipant: wrapped in catch (IOException) logging at WARN, never allowed to undo a container that was already created successfully. This also matters for testability — this class's existing tests deliberately pass a synthetic projectRoot="/repo" that doesn't exist on disk (see clientDataDirectory's own comment on why bind-mount sources aren't pre-created), and the real filesystem calls here would otherwise throw for every one of them. Tests that verify the actual symlinks use @TempDir (a real directory) instead.

Refusing a container action visibly (BL-191)

Actions that create containers (start, start-all) are validated synchronously, before the redirect. If no daemon is registered for the experiment, the handler redirects with ?msg=daemon-incompatible and the Containers tab renders the registry's message, naming the requested experiment and the supported ones.

Fixed defect. The daemon guard threw from inside createParticipant, which runs in backgroundExecutor whose only handling is catch (RuntimeException) { LOG.warn } — and the HTTP redirect had already been sent. Clicking "start" for MNIST/ECG5000/HAR/MIMIC returned a success redirect, created no container, and gave the operator nothing: a single line in the server log. Same failure-masking family as BL-181, which fixed exactly this in the consent endpoint.

Two deliberate scope decisions:

Path Behaviour Why
stop / stop-all not blocked destroying is always safe, and removing an orphaned container must stay possible — that is how the mislabeled containers from the BL-177 incident get cleaned up
autoLaunchDockerParticipants (from Start experiment / Run rounds) skips quietly at debug it is opportunistic, and those four experiments run fine in-process. Throwing here would break working functionality, so the visible error belongs only where the operator explicitly asked for a container

This is why the backlog's original suggestion — hard-fail all three entry points — was only partly right.

POST /api/experiments/{id}/create-participants now uses the same predicate. It previously had its own regex (exp-ergonomic-risk-\d+) while the service used startsWith("exp-ergonomic-risk") — two rules that could diverge, and did: the regex rejected clones with a non-numeric suffix that the service accepted.

DockerParticipantDaemonRegistry — which daemon runs for which experiment (BL-195)

Persistent Docker participants need a daemon class per role. That mapping used to be a constant on the Role enum plus a hardcoded experimentId.startsWith("exp-ergonomic-risk") check — an implicit rule with no extension point: adding a second daemon meant editing both.

It is now a registry, the same shape the project already uses to resolve which code runs for this experiment (ExperimentSessionFactory/sessionFactoryClass, ADR-005):

DockerParticipantDaemonRegistry.withDefaults()
        .withDaemon("exp-mnist-digits", new DaemonClasses(clientMain, aggregatorMain));

Registration is by prefix on purpose: a cloned experiment (exp-ergonomic-risk-002) shares the canonical experiment's daemon. That was already the startsWith semantics — the registry makes it explicit and configurable instead of accidental.

Scope, honestly. There is still exactly one daemon registered, and BL-195 had deferred this as speculative generality. What justifies it is not future extensibility but require(...): the refusal now names both the requested experiment and what is registered, instead of being an opaque constant. That message is what BL-191 needs to show the operator in place of today's silent redirect. supportsDockerParticipants(id) and incompatibleDaemonMessage(id) expose it for that use.

ALLOWED_CLIENT_IDS is the single source of truth for which clients the Docker path supports; AdminWebServer's start-all/stop-all actions read it rather than repeating the literal list, which previously would have desynced silently had the constant changed.

3f. Round tasks

Table with the compute plan tasks for this round: - Execution rank, task type, worker, status, error, diagnostics

3g. Round audit trail

Chronological table of all events recorded on the ledger for this round: - Event type (RegisterPreflightHash, RegisterLocalUpdateHash, etc.) - Actor (clientId, "aggregator", "orchestrator") - Evidence hash (abbreviated — 8 characters) - Relevant metadata (key=value; key=value) - Timestamp


4. Task plan (/experiments/{id}/tasks)

Inspired by Substra's Compute Plan concept. Displays all tasks in the experiment:

Summary cards: - Total · Completed · Running · Waiting · Failed · Cancelled

Full table: | Rank | Round | Task | Worker | Status | Error | Duration | Diagnostics | |---|---|---|---|---|---|---|---| | 1 | R1 | ROUND_CONFIG | orchestrator-001 | DONE | — | 0s | — | | 2 | R1 | LOCAL_TRAINING | client-1 | DONE | — | 12s | — | | 3 | R1 | LOCAL_TRAINING | client-2 | FAILED | PREFLIGHT_FAILED | 0s | min_samples | | ... | ... | ... | ... | ... | ... | ... | ... |

Recorded task types: - ROUND_CONFIG — publication of the round configuration - LOCAL_TRAINING — per-client local training - PREFLIGHT_CHECK — pre-training statistical validation - AGGREGATION — aggregation of updates - MODEL_PUBLICATION — publication of the candidate global model - CONSENT_REGISTRATION — registration of contract acceptance


5. Performances (/experiments/{id}/performances)

Displays the time series of metrics in a format equivalent to Substra's get_performances().

Summary cards: - Total points · Distinct rounds · Distinct workers · Distinct metrics · Highest value

Performance table: | Round | Identifier | Worker | Performance | Task | Updated | |---|---|---|---|---|---| | R1 | train_accuracy | client-3 | 0.8312 | training-R1-client-3 | 2026-05-27 14:22 | | R1 | train_accuracy | client-7 | 0.7894 | training-R1-client-7 | 2026-05-27 14:23 | | ... | ... | ... | ... | ... | ... |

Each row represents a metric observation for a specific client in a round. Allows tracking which clients improved or worsened round over round.


6. Global model history (/experiments/{id}/models)

Displays the evolutionary lineage of the federated model:

Summary: total registered versions + latest version.

Version table: | Version | Hash | URI | Tx | Registered | Download | |---|---|---|---|---|---| | v0 | sha256:a3f9... | file://artifacts/.../model.bin | tx-Seed... | 2026-05-27 14:00 | ⬇ Download model | | v1 | sha256:b7c2... | file://artifacts/.../model.bin | tx-Reg... | 2026-05-27 14:35 | ⬇ Download model | | ... | ... | ... | ... | ... | ... |

  • v0 = seed model registered by the researcher before the first round (seedGlobalModel)
  • v1, v2, ... = candidate models produced after each aggregation round

The hash and transaction ID are shown in abbreviated form (8 characters) for readability. The Tx points to the actual transaction on Fabric. The button downloads global-model-v{version}.csv via the route GET /api/experiments/{id}/models/{version}/content.


7. Hyperledger Assets (/experiments/{id}/assets)

Operational view of the assets registered on the ledger layer.

Summary by type: - Total · Contracts · Consents · Audit events

Asset table: | Asset | Logical key | Owner/actor | Status | Hash | Tx | Updated | |---|---|---|---|---|---|---| | ExperimentContractAsset | exp-har-001:1.0.0 | researcher-001 | ACTIVE | sha256:... | tx-... | ... | | ClientConsentAsset | exp-har-001:1.0.0:client-3 | client-3 | ACCEPTED | sha256:... | tx-... | ... | | AuditEventAsset | exp-har-001:R1:RegisterLocalUpdateHash | client-7 | — | sha256:... | tx-... | ... |

These assets reflect the world state recorded in Hyperledger Fabric.


8. Clients (/experiments/{id}/clients)

Detailed page with all clients of the experiment. Introduced in BL-045.

Summary: Total clients · Accepted · Pending · Rejected/Revoked

Clients table: | Client | Status (badge) | Timestamp | Tx ID | Dataset evidence | Participation | Actions | |---|---|---|---|---|---|---| | 1 | ACCEPTED | 2026-06-03 | tx-AcceptExperiment... | sha256 + schema | 3/3 (100%) | Accept / Reject |

Dataset evidence section: DatasetEvidence records per client — hash, metadata, schema, tx ID. Essential for LGPD auditing.


9. Blockchain Explorer (/experiments/{id}/blockchain)

Full explorer of all ledger assets for the experiment. Introduced in BL-045.

Summary by asset type (compact cards): ExperimentContract · TrainingCode · ClientConsent · DatasetEvidence · GlobalModel

Table by type: each row has a "👁 Visualizar" button (BL-203) that opens a modal (<dialog id="asset-modal">) with all of that asset's fields and values — logicalKey, transactionId, evidenceHash, timestamp, plus every dynamic field. The row's data is embedded as JSON in its data-fields attribute so the modal populates instantly with no round-trip to the server. Replaced the previous per-row inline expand (▶ campos / toggleDetail).

Audit Events: chronological table of all recorded events — type, round, actor, hash, tx ID, timestamp.


10. Configuration (/experiments/{id}/config)

Two-panel simulation configuration editor. Introduced in BL-045.

Read-only panel (active contract): - experimentId, coordinator, status, schema, aggregation policy, DP

Editable panel (session hyperparameters):

Fieldset Parameters
Federated Training rounds, epochs, LR, μ (FedProx), dropout, clipping
Fine-Tuning rounds, LR, μ, threshold k
Clients and Selection max clients, fraction, force all

Upon saving, the experiment's stateful session absorbs the new values before the next round.


Package deployment (/experiments/deploy)

ADR-005 / BL-058. Upload form (multipart/form-data) for a {experimentId}.hdtpkg.zip package generated by sh scripts/package-experiment.sh {experimentId}. Fields:

  • Package file (.zip, required) — submitted in the package field.
  • Expected clients — optional comma-separated list (clientIds), registered together with the contract for consent/monitoring purposes.

The page displays an explicit accepted-risk notice (no access control — see docs/components/15-experiment-packaging.md). On success, it redirects (303) to /experiments/{id}?version={contractVersion} of the newly deployed experiment.

BL-161: GET /experiments/deploy is intercepted before GET /experiments/{id} and always renders this form; therefore, the literal deploy is never treated as a contract id.

For clones that reuse a code package (BL-162), the research.xml screen reads the specification included in the deployed package. An edit is saved as a persistent overlay of the clone in var/, without modifying the XML or the source experiment's package.


JSON API

The JSON API allows integrating the monitor with external tools, dashboards, or automation scripts.

GET /api/experiments

Lists all experiments with a summary:

[
  {
    "experiment_id": "exp-har-smartphones-001",
    "contract_version": "1.0.0",
    "status": "ACTIVE",
    "coordinator_id": "researcher-har-001",
    "rounds": 3,
    "accepted_clients": 30
  }
]

GET /api/experiments/{id}/rounds?version=1.0.0

Lists all rounds with aggregated metrics:

[
  {
    "round_id": 1,
    "status": "COMPLETED",
    "accepted_clients": 18,
    "total_examples": 6300,
    "weighted_metric": 0.7812,
    "metric_name": "train_accuracy",
    "weighted_training_loss": 0.4218,
    "global_metric": 0.8120,
    "global_metric_name": "test_accuracy",
    "evaluation_dataset_hash": "sha256...",
    "average_update_norm": 312.45,
    "quorum_satisfied": true
  }
]

GET /api/experiments/{id}/performances?version=1.0.0

Series of performance points by round and client:

[
  {
    "round_id": 1,
    "identifier": "train_accuracy",
    "worker_id": "client-3",
    "performance": 0.8312,
    "task_key": "training-R1-client-3"
  }
]

GET /api/experiments/{id}/models

History of global model versions:

[
  {
    "model_version": 0,
    "model_hash": "sha256:a3f9e1b2...",
    "model_uri": "file://target/artifacts/.../model.bin",
    "transaction_id": "tx-Seed..."
  },
  {
    "model_version": 1,
    "model_hash": "sha256:b7c2d4e5...",
    "model_uri": "file://target/artifacts/.../model.bin",
    "transaction_id": "tx-RegisterGlobal..."
  }
]

11. Simulation Session (/experiments/{id}/sim-session)

Introduced in BL-053 and BL-054. Lets the researcher control per-round experiment execution via the browser, without a command line.

SimulationSession — state machine

Status Description
ACTIVE Session in progress — can advance rounds or pause
PAUSED Session paused — can resume or stop
DONE All rounds completed
ERROR Error in a round — currentRound was not changed

Usage flow

  1. Go to ▶ Session (tab in the experiment's navigation menu).
  2. Configure: adapter type (har or ecg), dataset path, number of clients, and total rounds.
  3. Click Start session → POST /sim-session/start.
  4. Advance one round at a time with Send round, or run all with ⏩ Run All Remaining Rounds.
  5. Use Pause / Resume as needed.
  6. Stop clears the session.

Session JSON API

// GET /api/experiments/{id}/sim-session — 200 with an active session
{
  "experiment_id": "exp-har-smartphones-001",
  "status": "ACTIVE",
  "current_round": 2,
  "total_rounds": 5,
  "last_message": ""
}

// 404 without a session:
{"error": "no active session"}

Environment variable

Variable Default Description
SIM_HMAC_SECRET "web-sim-secret-dev" HMAC secret for the session's MQTT envelopes. The -dev suffix indicates it is not suitable for production.

12. Ingestion Check (/experiments/{id}/ingestion-check)

Tab "🔎 Conferência", under Execução, next to 📡 Dados IoT.

The gap it closes

The Dados IoT tab shows what exists in timeseries.db, but not what should exist. A client missing from that table is ambiguous: the replay may never have published for it, or it may have published and the client never received it — two failures with opposite causes and opposite fixes. The check names the case by cross-referencing two figures the monitor already holds:

Figure Source
published SimulationRoundEngine.publishedByClient(experimentId) — accumulated per client from the ReplaySummary of every round sent
ingested AdminMonitoringService.simulationDataSummary(experimentId) — the store's own summary

The reconciliation itself is IngestionAudit.reconcile(...) (module federated-local-cdm, pure logic, no I/O) — see 07-data-component.md.

Reading the table

Column Meaning when wrong
Publicadas 0 the replay has not sent anything for this client in this monitor run — the baseline is in memory and resets on restart
Ingeridas 0 with publicadas > 0 the client did not subscribe, the HMAC signature does not verify, or the published senderId does not match the clientId (see ClientSenderScope)
Ingeridas > publicadas the client stored another sender's data — invalidates the non-IID partition and breaches data sovereignty
Faltando > 0 partial delivery: replay still running, or drops at signature/integrity verification

Routes

Method Route Response
GET /experiments/{id}/ingestion-check HTML page with per-client totals, delivery rate and status
GET /experiments/{id}/ingestion-check.json the same data as JSON
{
  "experiment_id": "exp-har-smartphones-001",
  "clients": [
    {
      "client_id": "1",
      "published": 1122,
      "ingested": 1122,
      "missing": 0,
      "entities": 2,
      "delivery_rate": 1.0000,
      "has_surplus": false,
      "health": "ok",
      "summary": "1122/1122 observacoes entregues"
    }
  ]
}

Baseline limits

The published baseline lives in SimulationRoundEngine's memory and is cumulative for the monitor process's lifetime — it is not persisted and it does not reset when a session stops. Consequences, all deliberate:

  • Restarting the monitor zeroes the baseline; clients already holding data appear with published = 0. The audit reports this as "not assessable" — never as a failure — and hasSurplus() requires published > 0 precisely so a missing baseline cannot be mistaken for contamination.
  • Clients present only in the baseline (published, nothing stored) still appear, with ingested = 0. That is the single most important row to display, so it is never filtered out.

Actions available in the monitor

Start round

The "Start round" button triggers the executor registered for the experiment:

Experiment Executor triggered
exp-har-smartphones-001 HarFederatedExperimentApp.run(null, false)

The round runs synchronously. The monitor displays the result after the next auto-refresh (30 s) or after reloading the page.

Accept/Reject client

Registers the client's consent on the ledger: - Accept → ClientConsentChaincode.acceptContract(...) → status ACCEPTED - Reject → ClientConsentChaincode.rejectContract(...) → status REJECTED

The status badge is updated immediately in the consent table.

Pause

Transitions the contract from ACTIVE status to PAUSED. New rounds cannot be started while the contract is paused.


Ledger modes

BLOCKCHAIN is the only supported mode. Fabric is required; failures block the operation. Legacy launcher aliases do not provide a memory-only or hybrid mode.

Environment variables for Fabric

Variable Default Description
FEDERATED_LEDGER_MODE blockchain Ledger mode (only mode supported)
FABRIC_PEER_BIN detected via FABRIC_HOME Path to the peer binary
FABRIC_CHANNEL_NAME federated-channel Fabric channel
FABRIC_CHAINCODE_NAME federated-governance Name of the installed chaincode
FABRIC_FAIL_ON_ERROR true Fabric failures block the operation
SIM_HMAC_SECRET "web-sim-secret-dev" HMAC secret for MQTT envelopes published by the simulation session

Mandatory rules

  • The monitor must always start on port 8088.
  • If the port is in use, the script terminates the previous process before starting.
  • The monitor never displays raw data — only hashes, URIs, metadata, and authorized metrics.
  • Training failures appear as operational diagnostics, without logs containing sensitive data.
  • BLOCKCHAIN is the only supported mode; the monitor requires a configured Fabric network.
  • Fabric integration failures block the operation and are reported to the operator.
  • The "Start round" button never starts more than one round at a time for the same experiment.

Internal architecture of the federated-rest-api module

Main classes

Class Responsibility
AdminWebApp Entry point — reads port and ledger mode from args, creates AdminWebServer
AdminWebServer HTTP router — dispatches requests to renderers and handlers
AdminHtmlLayout Static HTML/CSS utilities: layout(), css(), badge(), row(), html(), experimentTabs()
AdminMonitoringService Stateful service: registration of experiments, rounds, metrics, consents, performances
AdminApplicationBootstrap Factory: creates AdminMonitoringService with the 3 default experiments
AdminExperimentExecutor Map of ExperimentSession per experiment (legacy HAR/ECG + dynamic ADR-005 registration)
ExperimentDeploymentService ADR-005: extracts, validates, and deploys an ExperimentPackage received via upload
MultipartFormParser multipart/form-data parser with no external dependencies, used by package upload
LedgerPort ADR-003 interface: abstracts ledger operations (createExperimentContract, registerTrainingRound, etc.)
InMemoryLedgerPort No-op implementation of LedgerPort — for tests and MEMORY mode
FabricCliLedgerMirror Implements LedgerPort and FabricExperimentBridge — mirrors to Fabric via CLI
ClientPseudonymService LGPD — generates SHA-256 pseudonyms for clientId before writing to the ledger
TlsConfig Creates an HttpServer or HttpsServer according to ADMIN_TLS_KEYSTORE
SimulationSession Immutable record with session state: status, currentRound, totalRounds, lastMessage
SimulationRoundEngine Thin facade (BL-246) delegating to a ClientDataFlowInjector — no MqttGateway field of its own
MqttClientDataFlowInjector (BL-246) Production ClientDataFlowInjector: manages the adapter cache (HAR/ECG/CSV) and actually executes MQTT replay rounds
ClientUpdateRelay (BL-242, federated-orchestrator) Cross-experiment client→aggregator relay hosted by AdminWebServer — see below

ClientUpdateRelay (cross-experiment, BL-242): when AdminWebServer is constructed with a non-null MqttGateway, it also constructs and starts ClientUpdateRelay.forAllExperiments(mqttGateway) — a defensive, cross-experiment layer for the Docker-authoritative path. It is never a dependency: every *FederatedSession and every Docker daemon already runs its own per-experiment ClientUpdateRelay (see 04-orchestrator.md), so this one only matters if some future composition root forgets to wire its own — duplicate relaying across both is harmless, since MqttClientUpdateCollector deduplicates by (experimentId, contractVersion, roundId, clientId). null when mqttGateway is null (no-MQTT construction, e.g. most unit tests).

LedgerPort — ADR-003

The LedgerPort interface decouples AdminMonitoringService from the Hyperledger Fabric implementation:

// MEMORY mode — unit tests without Fabric
AdminMonitoringService svc =
    AdminApplicationBootstrap.createMonitoringServiceWithPort(new InMemoryLedgerPort());

// HYBRID/BLOCKCHAIN mode — Fabric via CLI
FabricCliLedgerMirror mirror = new FabricCliLedgerMirror(FabricCliConfig.fromEnvironment(ledgerMode));
AdminMonitoringService svc = new AdminMonitoringService(contractChaincode, consentChaincode,
    experimentChaincode, mirror, executor);

Operations covered by LedgerPort: createExperimentContract, registerTrainingCode, publishExperimentContract, activateExperimentContract, pauseExperimentContract, acceptExperimentContract, rejectExperimentContract, registerDatasetEvidence, registerTrainingRound, registerLocalUpdateHash, registerAggregationHash, registerGlobalModelVersion.

ExperimentDeploymentService — ADR-005

ADR-005: ExperimentSession/ExperimentSessionFactory lived in br.ufma.lsdi.admin until this delivery and were moved to federated-experiment-sdk (br.ufma.lsdi.experiment.sdk) so that packaged experiments can implement them without depending on the entire administrative module. Research experiment sources are added to the Maven build through build-helper configuration; dynamic deployment uses ExperimentDeploymentService and reflection. The simulator module does not depend on federated-rest-api (ADR-004), so the dependency graph remains acyclic.

AdminExperimentExecutor.registerFactory(experimentId, contractVersion, factory) registers a dynamically loaded ExperimentSessionFactory, with priority over the legacy hardcoded switch for HAR/ECG/DT. The executor keeps dynamic sessions per (experimentId, contractVersion) pair, allowing coexistence between different versions of the same experiment; when execute(experimentId) is called without an explicit version, it uses the most recently registered dynamic version for that experimentId. When starting a round from the monitor, AdminMonitoringService.startExperiment(...) propagates the newly registered roundId to the executor, so that stateful sessions never reuse the 1 identifier across consecutive initializations. ExperimentDeploymentService.deploy(zipBytes, clientIds):

  1. Extracts the zip via ExperimentPackageReader (zip slip/bomb, SHA256SUMS, packageFormatVersion).
  2. Moves the extracted content to ExperimentRuntimePaths.deployedExperimentDirectory(experimentId, contractVersion, shortHash).
  3. Validates sessionFactoryClass by launching a disposable isolated OS process (own PID/JVM) and sending it a VALIDATE command — the class is loaded and instantiated in that separate process, never inside admin-api's own JVM (br.ufma.lsdi.admin.isolated.*, BL-236).
  4. Registers an IsolatedExperimentSessionFactory in the executor and creates an ExperimentContract (ExperimentContractFactory.buildDraft(...).withStatus(ACTIVE)) via AdminMonitoringService.registerExperiment(...). Every later round also runs in an isolated process, launched on demand — see "Process isolation (BL-236)" in docs/components/15-experiment-packaging.md.

POST /experiments/{id}/reset-session respects ?version=/contractVersion, discarding only the stateful session for that version. This prevents resetting the new version from invalidating the session of an older version still running on the same monitor.

See docs/components/15-experiment-packaging.md for the package format, the full deployment flow, and the endpoint's remaining accepted risk (no access control of its own on /experiments/deploy).

AdminHtmlLayout — CSS/HTML utilities

Extracted from AdminWebServer (ADR-001 refactor). Static methods that are testable without a server:

String page = AdminHtmlLayout.layout("Experiment", body);
String b    = AdminHtmlLayout.badge("ACCEPTED");     // → <span class="badge ACCEPTED">...</span>
String r    = AdminHtmlLayout.row("Version", "1.0.0"); // → <dt>Version</dt><dd>1.0.0</dd>
String tabs = AdminHtmlLayout.experimentTabs("exp-001", "1.0.0", "overview");

experimentTabs(...) now renders the experiment navigation in two levels: at the top, only the categories (General, Execution, Monitoring, Configuration, Governance, Results); below, a strip of subtabs showing only the features of the active category. Existing routes have not changed: clicking a category navigates to its default feature, and the subtabs continue pointing to pages such as overview, clients, mqtt-monitor, performances, etc.

Blockchain

The project uses Hyperledger Fabric to record contracts, consents, hashes, URIs, and events. The Fabric installation is at blockchain/hyperledger-fabric/ (Google Drive).

FabricCliLedgerMirror (in modules/federated-rest-api) implements LedgerPort and FabricExperimentBridge, mirroring every audit operation to the blockchain via the peer CLI.


Current state

The MVP has a simple Java web server, without Spring Boot, run by scripts/run-admin-web.sh.

The monitor incorporates concepts inspired by Substra without depending on the Substra/SubstraFL stack:

  • ComputePlanTaskMonitor → configuration, training, aggregation, and publication tasks
  • PerformanceMonitorPoint → metrics per round, worker, and identifier
  • ClientRoundMetric.failedChecks → preflight failure diagnostics without exposing data
  • ContainerRunSummary → container, image, status, exit code, and logs per client
  • EpochPoint → loss, accuracy, and gradient norm per epoch (propagated up to the monitor)
  • perClassAccuracy → per-class accuracy per client (visualized as horizontal bars)

The recommended evolution is to migrate the administrative API to Spring Boot or Quarkus while keeping the same domain contracts.


/health and the ledger mode

GET /health reports status, ledgerMode, Fabric operational state, and fabricBlocker. BLOCKCHAIN is the only supported ledger mode. When Fabric is blocked, the endpoint returns HTTP 503 with status: "unhealthy"; when Fabric is operational, it returns HTTP 200 with status: "ok".

The current implementation does not automatically restore Fabric operational state after a connection failure; the process may need to be restarted after the underlying network or configuration problem is corrected.

Fabric mirroring: idempotent failure vs real failure (BL-192)

FabricGatewayLedgerMirror.submit(...) returns a three-valued SubmitOutcome, not a boolean:

Outcome Meaning
SUBMITTED transaction accepted by the ledger
ALREADY_REGISTERED chaincode rejected it as a duplicate — expected idempotent resubmission
FAILED genuine failure (network, config, operational block) — nothing was audited

Only ALREADY_REGISTERED adds the experiment to rehydratedContracts, the set that makes registerTrainingCode/publishExperimentContract/activateExperimentContract skip execution.

Fixed defect. All three collapsed into false, and createExperimentContract read any false as "already registered". A single transient failure therefore marked the experiment+version as rehydrated — permanently and silently disabling the rest of its on-chain audit trail for the process's lifetime, with no error signal. Only a genuine "already exists" proves the contract is on the ledger; FAILED proves nothing.

isIdempotentFailure now matches the same patterns FabricCliLedgerMirror already recognised — the CLI mirror was correct while the Gateway mirror lagged behind:

asset ja registrado · contrato ja existe · codigo de treinamento ja registrado
already_exists · training_code_already_registered · invalid_contract_transition · contract_immutable

"Codigo de treinamento ja registrado" is the real message from ExperimentContractSmartContract.requireMissing(...) for a duplicate registerTrainingCode; it matched neither of the two original patterns, so a harmless rehydration race was classified as a genuine failure and blocked auditing.


Concurrency, HTTP pool, SSE capacity, and async round execution (BL-334)

Root causes resolved after diagnosing a live production monitor freeze:

  1. Lock decoupling in AdminMonitoringService.prepareRoundExecution and AdminExperimentExecutor:
  2. prepareRoundExecution is no longer synchronized on AdminMonitoringService. It acquires the monitor lock only inside ensureExperimentActiveForExecution(...) to validate/activate contract state and read metadata, then invokes AdminExperimentExecutor.getOrCreateSession(...) outside the global monitor lock so concurrent readers (experiments(), experimentView(), UI routes) and consent mutations (acceptClient()) never stall behind dataset downloads or initial MQTT replays.
  3. AdminExperimentExecutor.getOrCreateSession(...) uses a per-key ReentrantLock (sessionCreationLocks, keyed by (experimentId, contractVersion)) rather than holding the global executor monitor during session instantiation. A sessionGenerations counter prevents a concurrent resetSession or unregisterFactory from caching an invalidated session.
  4. HTTP thread-pool sizing and SSE headroom (AdminWebServer / SseEventBus):
  5. AdminWebServer.maxHttpThreadsForCores(int) sets a floor of Math.max(64, Math.max(1, cores) * 8) HTTP worker threads, and httpExecutor uses corePoolSize = MAX_HTTP_THREADS with allowCoreThreadTimeOut(true) — preventing LinkedBlockingQueue from capping active HTTP threads below corePoolSize before queuing 512 requests.
  6. SseEventBus.DEFAULT_MAX_CONNECTIONS was lowered from 64 to 24 (< 64), guaranteeing abundant non-SSE HTTP threads for /health and UI navigation even on 4-vCPU hosts.
  7. Bounded synchronous wait for start/round triggers (AdminWebServer):
  8. HTML POST /experiments/{id}/start, POST /experiments/{id}/run-rounds, and API POST /api/experiments/{id}/start, POST /api/experiments/{id}/run-rounds run in a dedicated roundExecutionExecutor (16 threads, queue 128, allowCoreThreadTimeOut(true)) via runBoundedRoundAction(...). Fast executions complete synchronously within ADMIN_ROUND_SYNC_TIMEOUT_MS (default 15000 ms); slow initializations return immediately with HTTP 303 (?msg=execution-running banner in renderExperiment) or HTTP 202 ({"status":"RUNNING",...}) while execution completes in the background.
  9. Dataset downloader timeouts (HarDatasetLoader / Ecg5000DatasetLoader):
  10. Remote ZIP downloads enforce bounded TCP connect (10s) and socket read (30s) timeouts and download into a temporary .part file moved atomically on completion, preventing thread hangs or truncated ZIP cache corruption.