Running the session

This page walks through the full federated training session: starting the backend, registering three clients, creating a training proposal, granting consent, running the Flower clients, and inspecting the results.

1. Start the backend

python app/run_backend.py

The backend starts on port 8000 with the federated coordinator active.

2. Start the frontend

In a second terminal:

cd app/frontend
npm run dev

Open http://localhost:3000 and select Server admin mode. The dashboard shows zero connected clients.

3. Register clients

Open three additional browser tabs, each in Client node mode on ports 3001, 3002, and 3003 (mapping to Hospital_1, Hospital_2, Hospital_3).

In each client tab, load the corresponding data split:

• Client 1: upload example/IBD/data/federated/client_1/profile.tsv and metadata.tsv
• Client 2: upload example/IBD/data/federated/client_2/profile.tsv and metadata.tsv
• Client 3: upload example/IBD/data/federated/client_3/profile.tsv and metadata.tsv

The frontend computes quality metrics (sparsity, class distribution, feature coverage) locally in the browser and sends only those summary statistics to the server during registration. Raw data stays on the client.

After registration, the admin dashboard shows three connected clients with their data summaries.

Alternative: register via the API

curl -X POST http://localhost:8000/api/clients/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "client_1",
    "num_samples": 73,
    "num_features": 71013,
    "data_sparsity": 0.95,
    "class_distribution": {"CD": 29, "UC": 25, "Control": 19},
    "feature_coverage": 0.05
  }'

Repeat for client_2 and client_3 with their respective counts.

4. Create a training session

From the admin dashboard, create a new training session with the following settings:

Or via the API:

curl -X POST http://localhost:8000/api/training/start \
  -H "Content-Type: application/json" \
  -d '{
    "model_type": "xgboost",
    "target_column": "Study.Group",
    "feature_strategy": "intersection",
    "num_rounds": 10,
    "sample_id_column": "Sample",
    "auto_start": true
  }'

The coordinator creates a proposal and moves to the awaiting_consent state. Each client tab shows the proposal along with a code preview of the exact training code.

5. Submit consent

In each client tab, review the proposal and click Accept. Or via the API:

curl -X POST "http://localhost:8000/api/training/sessions/{session_id}/consent?client_id=client_1&consent=true"
curl -X POST "http://localhost:8000/api/training/sessions/{session_id}/consent?client_id=client_2&consent=true"
curl -X POST "http://localhost:8000/api/training/sessions/{session_id}/consent?client_id=client_3&consent=true"

Because auto_start=true, the coordinator launches the Flower server as soon as all clients have consented. The session status moves to running and the client tabs display the Flower server address.

6. Run the Flower clients

Each client needs to run a local Flower worker that loads its data and connects to the server. Open three terminals and run:

Terminal 1 (client_1):

python example/IBD/run_flower_client.py \
  --server-address 127.0.0.1:9080 \
  --profile example/IBD/data/federated/client_1/profile.tsv \
  --metadata example/IBD/data/federated/client_1/metadata.tsv \
  --sample-id-column Sample

Terminal 2 (client_2):

python example/IBD/run_flower_client.py \
  --server-address 127.0.0.1:9080 \
  --profile example/IBD/data/federated/client_2/profile.tsv \
  --metadata example/IBD/data/federated/client_2/metadata.tsv \
  --sample-id-column Sample

Terminal 3 (client_3):

python example/IBD/run_flower_client.py \
  --server-address 127.0.0.1:9080 \
  --profile example/IBD/data/federated/client_3/profile.tsv \
  --metadata example/IBD/data/federated/client_3/metadata.tsv \
  --sample-id-column Sample

Each client loads its local data, connects to the Flower server, and trains locally for 10 rounds. After each round, only the XGBoost model parameters are sent to the server for aggregation.

Note: The --server-address value comes from the session details. The default is 127.0.0.1:9080 when all clients are on the same machine.

7. Monitor training

The admin dashboard updates in real time as rounds complete. The analytics panel shows:

• Per-round loss and AUC across clients.
• Convergence status (whether the global model has stabilised).
• Aggregated feature importance from all clients.

Or poll the API:

curl http://localhost:8000/api/analytics/session/{session_id}

8. Results

After 10 rounds the session status moves to completed. The session record contains:

The global model is formed by aggregating XGBoost trees from all three sites. No raw data left any client machine during training.