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.0to select the contract version. The default is1.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/eventsremoved (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/_PASSWORDinTlsConfig) 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-roundswith live Docker participants (BL-200):triggerRoundForExternalParticipants(the callrun-rounds/startmake 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 thenumRoundsrequested back-to-back in milliseconds, long before any of them could possibly have been aggregated (a real incident:exp-ergonomic-risk-002had 10 rounds fire in a ~30ms burst, all with 0 clients and a corrupted model-version sequence — see BL-200/BL-201 inbacklog.md).run-roundsnow refuses to trigger a new Docker round while the previous one is still unresolved: it throwsIllegalStateExceptionnaming 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: arun-roundscall with Docker participants live andnumRounds > 1will only ever execute 1 new round per call — call it again after that round resolves (visible viaGET /api/experiments/{id}/roundsor theround-completedSSE event) to progress further.Where that logic lives (BL-195/BL-196): the body of
triggerRoundForExternalParticipantsis no longer written out in each of the 5*FederatedSessionclasses. They now delegate toExternalParticipantRoundTrigger(modulefederated-orchestrator), which owns the single- publication guard, thestartRoundWithHyperparameters/finalizeRoundpair and theglobalModelVersionadvance. 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
synchronizedon the trigger instance instead of a barebooleanwhose correctness silently depended on an externalReentrantLockno 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
2b. Client consent¶
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).
activeClientParticipantIdsused to be built onlistParticipants. It sits on the hot path —AdminMonitoringService.setDockerParticipantsLiveCheckconsults 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 fordocker info, at 19× the scale: a degraded Docker daemon stalled every round for minutes.It now issues a single
docker pswithlabel=…experiment,label=…role=clientandstatus=running, letting Docker do the filtering. TheparticipantIdis derived from the container name instead of adocker inspectof the environment:containerName()is deterministic and its sanitisation is per-character, so the prefix generated with an emptyparticipantIdis 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 inbackgroundExecutorwhose only handling iscatch (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)andincompatibleDaemonMessage(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}.csvvia the routeGET /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 thepackagefield. - 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¶
- Go to ▶ Session (tab in the experiment's navigation menu).
- Configure: adapter type (
harorecg), dataset path, number of clients, and total rounds. - Click Start session → POST
/sim-session/start. - Advance one round at a time with Send round, or run all with ⏩ Run All Remaining Rounds.
- Use Pause / Resume as needed.
- 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 — andhasSurplus()requirespublished > 0precisely 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.
BLOCKCHAINis 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/ExperimentSessionFactorylived inbr.ufma.lsdi.adminuntil this delivery and were moved tofederated-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 usesExperimentDeploymentServiceand reflection. The simulator module does not depend onfederated-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):
- Extracts the zip via
ExperimentPackageReader(zip slip/bomb,SHA256SUMS,packageFormatVersion). - Moves the extracted content to
ExperimentRuntimePaths.deployedExperimentDirectory(experimentId, contractVersion, shortHash). - Validates
sessionFactoryClassby launching a disposable isolated OS process (own PID/JVM) and sending it aVALIDATEcommand — the class is loaded and instantiated in that separate process, never inside admin-api's own JVM (br.ufma.lsdi.admin.isolated.*, BL-236). - Registers an
IsolatedExperimentSessionFactoryin the executor and creates anExperimentContract(ExperimentContractFactory.buildDraft(...).withStatus(ACTIVE)) viaAdminMonitoringService.registerExperiment(...). Every later round also runs in an isolated process, launched on demand — see "Process isolation (BL-236)" indocs/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 tasksPerformanceMonitorPoint→ metrics per round, worker, and identifierClientRoundMetric.failedChecks→ preflight failure diagnostics without exposing dataContainerRunSummary→ container, image, status, exit code, and logs per clientEpochPoint→ 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, andcreateExperimentContractread anyfalseas "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;FAILEDproves 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:
- Lock decoupling in
AdminMonitoringService.prepareRoundExecutionandAdminExperimentExecutor: prepareRoundExecutionis no longersynchronizedonAdminMonitoringService. It acquires the monitor lock only insideensureExperimentActiveForExecution(...)to validate/activate contract state and read metadata, then invokesAdminExperimentExecutor.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.AdminExperimentExecutor.getOrCreateSession(...)uses a per-keyReentrantLock(sessionCreationLocks, keyed by(experimentId, contractVersion)) rather than holding the global executor monitor during session instantiation. AsessionGenerationscounter prevents a concurrentresetSessionorunregisterFactoryfrom caching an invalidated session.- HTTP thread-pool sizing and SSE headroom (
AdminWebServer/SseEventBus): AdminWebServer.maxHttpThreadsForCores(int)sets a floor ofMath.max(64, Math.max(1, cores) * 8)HTTP worker threads, andhttpExecutorusescorePoolSize = MAX_HTTP_THREADSwithallowCoreThreadTimeOut(true)— preventingLinkedBlockingQueuefrom capping active HTTP threads belowcorePoolSizebefore queuing 512 requests.SseEventBus.DEFAULT_MAX_CONNECTIONSwas lowered from64to24(< 64), guaranteeing abundant non-SSE HTTP threads for/healthand UI navigation even on 4-vCPU hosts.- Bounded synchronous wait for start/round triggers (
AdminWebServer): - HTML
POST /experiments/{id}/start,POST /experiments/{id}/run-rounds, and APIPOST /api/experiments/{id}/start,POST /api/experiments/{id}/run-roundsrun in a dedicatedroundExecutionExecutor(16threads, queue128,allowCoreThreadTimeOut(true)) viarunBoundedRoundAction(...). Fast executions complete synchronously withinADMIN_ROUND_SYNC_TIMEOUT_MS(default15000ms); slow initializations return immediately with HTTP303(?msg=execution-runningbanner inrenderExperiment) or HTTP202({"status":"RUNNING",...}) while execution completes in the background. - Dataset downloader timeouts (
HarDatasetLoader/Ecg5000DatasetLoader): - Remote ZIP downloads enforce bounded TCP connect (
10s) and socket read (30s) timeouts and download into a temporary.partfile moved atomically on completion, preventing thread hangs or truncated ZIP cache corruption.