# kumarjitdron/healchain architecture

> Architecture diagram of the GitHub repository kumarjitdron/healchain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kumarjitdron/healchain
- Repository: https://github.com/kumarjitdron/healchain

## Overview

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: [`frontend/src/app`](https://github.com/kumarjitdron/healchain/tree/main/frontend/src/app) (Workflow UI), [`aggregator/src/main.py`](https://github.com/kumarjitdron/healchain/blob/main/aggregator/src/main.py) (M4-M5 orchestration), [`backend/src/api/aggregatorRoutes.ts`](https://github.com/kumarjitdron/healchain/blob/main/backend/src/api/aggregatorRoutes.ts) (Aggregator API), [`contracts`](https://github.com/kumarjitdron/healchain/tree/main/contracts) (Protocol contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User workflow"]
  node_web["Workflow UI"]
  node_wallet["Wallet integration<br/>[useWallet.ts]"]
end

subgraph group_backend["Coordination backend"]
  node_task_api["Task API<br/>[taskRoutes.ts]"]
  node_miner_api["Miner API<br/>[minerRoutes.ts]"]
  node_aggregator_api["Aggregator API"]
  node_verification_api["Verification API"]
  node_task_service["Task lifecycle<br/>[taskService.ts]"]
  node_selection["Miner selection"]
  node_training_orchestrator["Training orchestration"]
  node_aggregation_orchestrator["Aggregation orchestration"]
  node_verification["Feedback verification"]
  node_reward_service["Reward coordination<br/>[rewardService.ts]"]
  node_database[("Task persistence<br/>[database.config.ts]")]
end

subgraph group_miner["Miner runtime"]
  node_fl_client["Miner training service<br/>[trainer.py]"]
  node_miner_lifecycle["Local task lifecycle<br/>[lifecycle.py]"]
end

subgraph group_aggregation["Aggregation runtime"]
  node_collector["Submission collector<br/>[collector.py]"]
  node_secure_aggregation["Decrypt and recover<br/>[aggregator.py]"]
  node_crypto{{"FE and BSGS crypto<br/>[ndd_fe.py]"}}
  node_candidate["Candidate consensus<br/>[candidate.py]"]
  node_aggregator_main["M4-M5 orchestration<br/>[main.py]"]
end

subgraph group_chain["On-chain protocol"]
  node_contracts["Protocol contracts"]
  node_escrow["Escrow"]
  node_publisher_contract["Block publication"]
  node_rewards_contract["Reward distribution"]
end

node_publisher(("Publisher"))
node_participants(("Miners and verifiers"))
node_ipfs[("IPFS artifacts")]

node_publisher -->|"publishes task"| node_web
node_participants -->|"registers and reviews"| node_web
node_web -->|"signs actions"| node_wallet
node_web -->|"requests task actions"| node_task_api
node_web -->|"requests participation"| node_miner_api
node_task_api -->|"creates and reads"| node_task_service
node_task_service -->|"persists tasks"| node_database
node_task_service -->|"checks escrow"| node_escrow
node_miner_api -->|"registers miners"| node_selection
node_selection -->|"records selection"| node_database
node_selection -->|"checks stake"| node_contracts
node_miner_api -->|"triggers training"| node_training_orchestrator
node_training_orchestrator -->|"starts training"| node_fl_client
node_participants -->|"trains locally"| node_fl_client
node_fl_client -->|"submits encrypted updates"| node_aggregator_api
node_aggregator_api -->|"triggers aggregation"| node_aggregation_orchestrator
node_aggregation_orchestrator -->|"dispatches aggregation"| node_aggregator_main
node_aggregator_main -->|"fetches submissions"| node_collector
node_collector -.->|"provides submissions"| node_secure_aggregation
node_secure_aggregation -->|"uses FE and BSGS"| node_crypto
node_aggregator_main -->|"constructs candidate"| node_candidate
node_aggregator_main -.->|"loads or stores artifacts"| node_ipfs
node_candidate -->|"submits candidate"| node_verification_api
node_participants -->|"sends feedback"| node_verification_api
node_verification_api -->|"validates feedback"| node_verification
node_verification -.->|"returns feedback"| node_aggregator_main
node_aggregator_api -->|"publishes verified block"| node_publisher_contract
node_publisher -->|"reveals accuracy"| node_rewards_contract
node_participants -->|"reveals scores"| node_rewards_contract
node_aggregator_api -.->|"coordinates rewards"| node_reward_service
node_reward_service -->|"distributes rewards"| node_rewards_contract
node_contracts -.->|"includes"| node_escrow
node_contracts -.->|"includes"| node_publisher_contract
node_contracts -.->|"includes"| node_rewards_contract

click node_web "https://github.com/kumarjitdron/healchain/tree/main/frontend/src/app"
click node_wallet "https://github.com/kumarjitdron/healchain/blob/main/frontend/src/hooks/useWallet.ts"
click node_task_api "https://github.com/kumarjitdron/healchain/blob/main/backend/src/api/taskRoutes.ts"
click node_miner_api "https://github.com/kumarjitdron/healchain/blob/main/backend/src/api/minerRoutes.ts"
click node_aggregator_api "https://github.com/kumarjitdron/healchain/blob/main/backend/src/api/aggregatorRoutes.ts"
click node_verification_api "https://github.com/kumarjitdron/healchain/blob/main/backend/src/api/verificationRoutes.ts"
click node_task_service "https://github.com/kumarjitdron/healchain/blob/main/backend/src/services/taskService.ts"
click node_selection "https://github.com/kumarjitdron/healchain/blob/main/backend/src/services/minerSelectionService.ts"
click node_training_orchestrator "https://github.com/kumarjitdron/healchain/blob/main/backend/src/services/trainingOrchestrationService.ts"
click node_aggregation_orchestrator "https://github.com/kumarjitdron/healchain/blob/main/backend/src/services/aggregatorOrchestrationService.ts"
click node_verification "https://github.com/kumarjitdron/healchain/blob/main/backend/src/services/verificationService.ts"
click node_reward_service "https://github.com/kumarjitdron/healchain/blob/main/backend/src/services/rewardService.ts"
click node_database "https://github.com/kumarjitdron/healchain/blob/main/backend/src/config/database.config.ts"
click node_fl_client "https://github.com/kumarjitdron/healchain/blob/main/fl_client/src/training/trainer.py"
click node_miner_lifecycle "https://github.com/kumarjitdron/healchain/blob/main/fl_client/src/tasks/lifecycle.py"
click node_collector "https://github.com/kumarjitdron/healchain/blob/main/aggregator/src/aggregation/collector.py"
click node_secure_aggregation "https://github.com/kumarjitdron/healchain/blob/main/aggregator/src/aggregation/aggregator.py"
click node_crypto "https://github.com/kumarjitdron/healchain/blob/main/aggregator/src/crypto/ndd_fe.py"
click node_candidate "https://github.com/kumarjitdron/healchain/blob/main/aggregator/src/consensus/candidate.py"
click node_aggregator_main "https://github.com/kumarjitdron/healchain/blob/main/aggregator/src/main.py"
click node_contracts "https://github.com/kumarjitdron/healchain/tree/main/contracts"
click node_escrow "https://github.com/kumarjitdron/healchain/tree/main/contracts"
click node_publisher_contract "https://github.com/kumarjitdron/healchain/tree/main/contracts"
click node_rewards_contract "https://github.com/kumarjitdron/healchain/tree/main/contracts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_wallet toneBlue
class node_task_api,node_miner_api,node_aggregator_api,node_verification_api,node_task_service,node_selection,node_training_orchestrator,node_aggregation_orchestrator,node_verification,node_reward_service,node_database,node_ipfs toneAmber
class node_fl_client,node_miner_lifecycle toneMint
class node_collector,node_secure_aggregation,node_crypto,node_candidate,node_aggregator_main toneRose
class node_contracts,node_escrow,node_publisher_contract,node_rewards_contract,node_publisher,node_participants toneIndigo
```

## Components

### User workflow

- [Workflow UI](https://github.com/kumarjitdron/healchain/tree/main/frontend/src/app): `frontend/src/app`
- [Wallet integration](https://github.com/kumarjitdron/healchain/blob/main/frontend/src/hooks/useWallet.ts): `frontend/src/hooks/useWallet.ts`

### Coordination backend

- [Task API](https://github.com/kumarjitdron/healchain/blob/main/backend/src/api/taskRoutes.ts): `backend/src/api/taskRoutes.ts`
- [Miner API](https://github.com/kumarjitdron/healchain/blob/main/backend/src/api/minerRoutes.ts): `backend/src/api/minerRoutes.ts`
- [Aggregator API](https://github.com/kumarjitdron/healchain/blob/main/backend/src/api/aggregatorRoutes.ts): `backend/src/api/aggregatorRoutes.ts`
- [Verification API](https://github.com/kumarjitdron/healchain/blob/main/backend/src/api/verificationRoutes.ts): `backend/src/api/verificationRoutes.ts`
- [Task lifecycle](https://github.com/kumarjitdron/healchain/blob/main/backend/src/services/taskService.ts): `backend/src/services/taskService.ts`
- [Miner selection](https://github.com/kumarjitdron/healchain/blob/main/backend/src/services/minerSelectionService.ts): `backend/src/services/minerSelectionService.ts`
- [Training orchestration](https://github.com/kumarjitdron/healchain/blob/main/backend/src/services/trainingOrchestrationService.ts): `backend/src/services/trainingOrchestrationService.ts`
- [Aggregation orchestration](https://github.com/kumarjitdron/healchain/blob/main/backend/src/services/aggregatorOrchestrationService.ts): `backend/src/services/aggregatorOrchestrationService.ts`
- [Feedback verification](https://github.com/kumarjitdron/healchain/blob/main/backend/src/services/verificationService.ts): `backend/src/services/verificationService.ts`
- [Reward coordination](https://github.com/kumarjitdron/healchain/blob/main/backend/src/services/rewardService.ts): `backend/src/services/rewardService.ts`
- [Task persistence](https://github.com/kumarjitdron/healchain/blob/main/backend/src/config/database.config.ts): `backend/src/config/database.config.ts`

### Miner runtime

- [Miner training service](https://github.com/kumarjitdron/healchain/blob/main/fl_client/src/training/trainer.py): `fl_client/src/training/trainer.py`
- [Local task lifecycle](https://github.com/kumarjitdron/healchain/blob/main/fl_client/src/tasks/lifecycle.py): `fl_client/src/tasks/lifecycle.py`

### Aggregation runtime

- [Submission collector](https://github.com/kumarjitdron/healchain/blob/main/aggregator/src/aggregation/collector.py): `aggregator/src/aggregation/collector.py`
- [Decrypt and recover](https://github.com/kumarjitdron/healchain/blob/main/aggregator/src/aggregation/aggregator.py): `aggregator/src/aggregation/aggregator.py`
- [FE and BSGS crypto](https://github.com/kumarjitdron/healchain/blob/main/aggregator/src/crypto/ndd_fe.py): `aggregator/src/crypto/ndd_fe.py`
- [Candidate consensus](https://github.com/kumarjitdron/healchain/blob/main/aggregator/src/consensus/candidate.py): `aggregator/src/consensus/candidate.py`
- [M4-M5 orchestration](https://github.com/kumarjitdron/healchain/blob/main/aggregator/src/main.py): `aggregator/src/main.py`

### On-chain protocol

- [Protocol contracts](https://github.com/kumarjitdron/healchain/tree/main/contracts): `contracts`
- [Escrow](https://github.com/kumarjitdron/healchain/tree/main/contracts): `contracts`
- [Block publication](https://github.com/kumarjitdron/healchain/tree/main/contracts): `contracts`
- [Reward distribution](https://github.com/kumarjitdron/healchain/tree/main/contracts): `contracts`

### Other components

- **Publisher**
- **Miners and verifiers**
- **IPFS artifacts**

## Connections

- Publisher → Workflow UI: publishes task (evidence: `README.md`)
- Miners and verifiers → Workflow UI: registers and reviews (evidence: `README.md`)
- Workflow UI → Wallet integration: signs actions (evidence: `frontend/src/hooks/useWallet.ts`)
- Workflow UI → Task API: requests task actions (evidence: `README.md`)
- Workflow UI → Miner API: requests participation (evidence: `README.md`)
- Task API → Task lifecycle: creates and reads (evidence: `backend/src/api/taskRoutes.ts`)
- Task lifecycle → Task persistence: persists tasks (evidence: `backend/src/services/taskService.ts`)
- Task lifecycle → Escrow: checks escrow (evidence: `backend/src/services/taskService.ts`)
- Miner API → Miner selection: registers miners (evidence: `backend/src/api/minerRoutes.ts`)
- Miner selection → Task persistence: records selection (evidence: `backend/src/services/minerSelectionService.ts`)
- Miner selection → Protocol contracts: checks stake (evidence: `backend/src/services/minerSelectionService.ts`)
- Miner API → Training orchestration: triggers training (evidence: `backend/src/api/minerRoutes.ts`)
- Training orchestration → Miner training service: starts training (evidence: `backend/src/services/trainingOrchestrationService.ts`)
- Miners and verifiers → Miner training service: trains locally (evidence: `README.md`)
- Miner training service → Aggregator API: submits encrypted updates (evidence: `README.md`)
- Aggregator API → Aggregation orchestration: triggers aggregation (evidence: `backend/src/api/aggregatorRoutes.ts`)
- Aggregation orchestration → M4-M5 orchestration: dispatches aggregation (evidence: `backend/src/services/aggregatorOrchestrationService.ts`)
- M4-M5 orchestration → Submission collector: fetches submissions (evidence: `aggregator/src/main.py`)
- Submission collector → Decrypt and recover: provides submissions
- Decrypt and recover → FE and BSGS crypto: uses FE and BSGS (evidence: `aggregator/src/aggregation/aggregator.py`)
- M4-M5 orchestration → Candidate consensus: constructs candidate (evidence: `aggregator/src/main.py`)
- M4-M5 orchestration → IPFS artifacts: loads or stores artifacts (evidence: `README.md`)
- Candidate consensus → Verification API: submits candidate (evidence: `README.md`)
- Miners and verifiers → Verification API: sends feedback (evidence: `README.md`)
- Verification API → Feedback verification: validates feedback (evidence: `backend/src/api/verificationRoutes.ts`)
- Feedback verification → M4-M5 orchestration: returns feedback
- Aggregator API → Block publication: publishes verified block (evidence: `README.md`)
- Publisher → Reward distribution: reveals accuracy (evidence: `README.md`)
- Miners and verifiers → Reward distribution: reveals scores (evidence: `README.md`)
- Aggregator API → Reward coordination: coordinates rewards
- Reward coordination → Reward distribution: distributes rewards (evidence: `README.md`)
- Protocol contracts → Escrow: includes
- Protocol contracts → Block publication: includes
- Protocol contracts → Reward distribution: includes