How kumarjitdron/healchain works
HealChain coordinates a federated-learning protocol from task publication through miner training, secure aggregation, participant verification, on-chain publication, and commit-reveal rewards. The frontend drives user actions; the backend coordinates services and persistence; miner and aggregator services perform off-chain computation; contracts record and enforce protocol outcomes. The README documents the end-to-end phases, while source excerpts confirm selected API dispatches and service calls. Several internals and contract implementations were not sampled, so their links are documented at subsystem level.
Main entry points: app Workflow UI · main.py M4-M5 orchestration · aggregatorRoutes.ts Aggregator API · contracts Protocol contracts
Components 27
User workflow
- Workflow UI
frontend/src/app - Wallet integration
frontend/src/hooks/useWallet.ts
Coordination backend
- Task API
backend/src/api/taskRoutes.ts - Miner API
backend/src/api/minerRoutes.ts - Aggregator API
backend/src/api/aggregatorRoutes.ts - Verification API
backend/src/api/verificationRoutes.ts - Task lifecycle
backend/src/services/taskService.ts - Miner selection
backend/src/services/minerSelectionService.ts - Training orchestration
backend/src/services/trainingOrchestrationService.ts - Aggregation orchestration
backend/src/services/aggregatorOrchestrationService.ts - Feedback verification
backend/src/services/verificationService.ts - Reward coordination
backend/src/services/rewardService.ts - Task persistence
backend/src/config/database.config.ts
Miner runtime
- Miner training service
fl_client/src/training/trainer.py - Local task lifecycle
fl_client/src/tasks/lifecycle.py
Aggregation runtime
- Submission collector
aggregator/src/aggregation/collector.py - Decrypt and recover
aggregator/src/aggregation/aggregator.py - FE and BSGS crypto
aggregator/src/crypto/ndd_fe.py - Candidate consensus
aggregator/src/consensus/candidate.py - M4-M5 orchestration
aggregator/src/main.py
On-chain protocol
- Protocol contracts
contracts - Escrow
contracts - Block publication
contracts - Reward distribution
contracts
Other components
- Publisher
- Miners and verifiers
- IPFS artifacts
Connections 34
- Publisher → Workflow UI: publishes task
README.md - Miners and verifiers → Workflow UI: registers and reviews
README.md - Workflow UI → Wallet integration: signs actions
frontend/src/hooks/useWallet.ts - Workflow UI → Task API: requests task actions
README.md - Workflow UI → Miner API: requests participation
README.md - Task API → Task lifecycle: creates and reads
backend/src/api/taskRoutes.ts - Task lifecycle → Task persistence: persists tasks
backend/src/services/taskService.ts - Task lifecycle → Escrow: checks escrow
backend/src/services/taskService.ts - Miner API → Miner selection: registers miners
backend/src/api/minerRoutes.ts - Miner selection → Task persistence: records selection
backend/src/services/minerSelectionService.ts - Miner selection → Protocol contracts: checks stake
backend/src/services/minerSelectionService.ts - Miner API → Training orchestration: triggers training
backend/src/api/minerRoutes.ts - Training orchestration → Miner training service: starts training
backend/src/services/trainingOrchestrationService.ts - Miners and verifiers → Miner training service: trains locally
README.md - Miner training service → Aggregator API: submits encrypted updates
README.md - Aggregator API → Aggregation orchestration: triggers aggregation
backend/src/api/aggregatorRoutes.ts - Aggregation orchestration → M4-M5 orchestration: dispatches aggregation
backend/src/services/aggregatorOrchestrationService.ts - M4-M5 orchestration → Submission collector: fetches submissions
aggregator/src/main.py - Submission collector → Decrypt and recover: provides submissions
- Decrypt and recover → FE and BSGS crypto: uses FE and BSGS
aggregator/src/aggregation/aggregator.py - M4-M5 orchestration → Candidate consensus: constructs candidate
aggregator/src/main.py - M4-M5 orchestration → IPFS artifacts: loads or stores artifacts
README.md - Candidate consensus → Verification API: submits candidate
README.md - Miners and verifiers → Verification API: sends feedback
README.md - Verification API → Feedback verification: validates feedback
backend/src/api/verificationRoutes.ts - Feedback verification → M4-M5 orchestration: returns feedback
- Aggregator API → Block publication: publishes verified block
README.md - Publisher → Reward distribution: reveals accuracy
README.md - Miners and verifiers → Reward distribution: reveals scores
README.md - Aggregator API → Reward coordination: coordinates rewards
- Reward coordination → Reward distribution: distributes rewards
README.md - Protocol contracts → Escrow: includes
- Protocol contracts → Block publication: includes
- Protocol contracts → Reward distribution: includes