Web interface

mllabiome ships with an optional web application for model inference, federated learning coordination, and training analytics. The application consists of a FastAPI backend and a Next.js frontend.

Installation

Install the app dependencies:


uv pip install -e ".[app]"

Install the frontend dependencies:


cd app/frontend
npm install

Starting the application

Backend


python app/run_backend.py

The backend starts on port 8000 by default. Use --port and --host to customise:


python app/run_backend.py --port 9000 --host 127.0.0.1

The interactive API documentation is available at http://localhost:8000/docs (Swagger UI).

Frontend

In a separate terminal:


cd app/frontend
npm run dev

The frontend starts on port 3000. Open http://localhost:3000 in a browser.

Operating modes

The landing page presents three operating modes:

Mode	Port	Description
Server admin	3000	Federated learning dashboard. Manage clients, create training sessions, view analytics.
Client node	3001-3008	Client-side interface. Load local data, review training proposals, submit consent. Each port maps to a hospital identifier (3001 = Hospital_1, 3002 = Hospital_2, etc.).
Inference	3000	Upload samples, select a deployed model, receive predictions with optional LIME explanations.

Configuration

Backend settings are loaded from environment variables or a .env file in the backend directory.

Variable	Default	Description
`EXPERIMENT_DIR`	`None`	Base experiment directory for model discovery
`CORS_EXTRA_ORIGINS`	`""`	Comma-separated additional CORS origins
`MAX_UPLOAD_SIZE`	10 MB	Maximum file upload size
`ENABLE_FEDERATED`	`true`	Enable the federated learning endpoints
`MAX_CLIENTS`	100	Maximum simultaneous federated clients
`ENABLE_ANALYTICS`	`true`	Enable the analytics engine

Frontend settings are configured through environment variables prefixed with NEXT_PUBLIC_:

Variable	Default	Description
`NEXT_PUBLIC_API_URL`	`http://localhost:8000`	Backend API base URL
`NEXT_PUBLIC_WS_URL`	`ws://localhost:8000`	WebSocket URL for real-time updates

API route groups

The backend registers the following route groups under /api:

Group	Prefix	Description
Health	`/api/health`	Liveness check
Inference	`/api/inference`	Model predictions and LIME explanations
Training	`/api/training`	Session creation, consent, execution
Clients	`/api/clients`	Client registration, heartbeat, status
Client data	`/api/clients/{id}/training`	Client training status and Flower connection
Analytics	`/api/analytics`	Federated training metrics and convergence
Data	`/api/data`	File download for clients
Chat	`/api/chat`	LLM-powered microbiome analysis (requires Ollama)
Research	`/api/research`	Disease task definitions and evaluation

Frontend components

Component	Purpose
`FLDashboard`	Server admin panel for client monitoring, training session control, and analytics display
`FederatedClient`	Client node UI for local data loading, proposal review, and consent submission
`InferenceInterface`	Model selection, file upload, prediction results, and LIME explanation requests
`ChatInterface`	Conversational interface for microbiome analysis (connects to Ollama)
`CompactAnalytics`	Summary statistics for connected clients and training progress
`AnalyticsVisualization`	Training curve and feature importance charts (built with Recharts)

Technology stack

Layer	Technology
Backend	FastAPI, uvicorn, Pydantic
Frontend	Next.js 14, React 18, TypeScript
Charts	Recharts
HTTP client	Axios (frontend), httpx (backend)
Federation	Flower (flwr)
Explanations	LIME