# phamnguyengiabao-dev/group2_hcmus_blockchain architecture

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

- Interactive diagram: https://gitdiagram.com/phamnguyengiabao-dev/group2_hcmus_blockchain
- Repository: https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain

## Overview

This repository is a deterministic Layer-1 blockchain simulator with a companion dashboard for inspecting simulation logs. The main workflow loads a scenario, initializes deterministic time and simulated networking, runs validator consensus through proposal, voting and finalization, and records events and ledger state. The dashboard loads scenario configuration and JSONL logs, derives chain and event views, and presents them interactively. The README and source index support the major subsystem links; unsampled module behavior is represented only where the index or README documents the relationship.

Main entry points: [`src/consensus.py`](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/consensus.py) (Consensus state), [`src/block.py`](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/block.py) (Blocks), [`src/scenario.py`](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/scenario.py) (Scenario runner), [`src/vote.py`](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/vote.py) (Votes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation orchestration"]
  node_scenario["Scenario runner<br/>[scenario.py]"]
  node_scenario_config["Scenario configs"]
  node_scheduler["Logical scheduler<br/>[scheduler.py]"]
  node_network["Simulated network<br/>[network.py]"]
  node_faults["Fault injector<br/>[fault_injector.py]"]
  node_legacy_runner["Legacy runner<br/>[scenario_runner.py]"]
end

subgraph group_protocol["Consensus protocol"]
  node_consensus["Consensus state<br/>[consensus.py]"]
  node_router["Message router<br/>[router.py]"]
  node_gossip["Peer gossip<br/>[gossip.py]"]
  node_transaction["Transactions<br/>[transaction.py]"]
  node_block["Blocks<br/>[block.py]"]
  node_block_validation["Block validation<br/>[block_validator.py]"]
  node_block_store[("Candidate block store<br/>[block_store.py]")]
  node_vote["Votes<br/>[vote.py]"]
  node_vote_set["Vote aggregation<br/>[vote_set.py]"]
  node_identity["Validator identities<br/>[identity.py]"]
  node_executor["Block executor<br/>[executor.py]"]
end

subgraph group_foundation["Protocol foundations"]
  node_crypto["Cryptography<br/>[crypto.py]"]
  node_encoding["Canonical encoding<br/>[encoding.py]"]
  node_state[("Key-value state<br/>[state.py]")]
end

subgraph group_observability["Logs and ledger"]
  node_ledger[("Finalized ledger<br/>[ledger.py]")]
  node_event_log["Event log<br/>[event_log.py]"]
  node_summary["Run summary<br/>[summary.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_app["Dashboard app<br/>[app.py]"]
  node_dashboard_layout["Dashboard layout<br/>[layout.py]"]
  node_dashboard_callbacks["Dashboard callbacks<br/>[callbacks.py]"]
  node_dashboard_data["Log and config loader<br/>[data_loader.py]"]
  node_dashboard_charts["Charts<br/>[charts.py]"]
  node_dashboard_components["UI components<br/>[components.py]"]
end

node_operator(("Scenario operator"))
node_dashboard_user(("Dashboard user"))

node_operator -->|"runs scenario"| node_scenario
node_scenario_config -->|"configures"| node_scenario
node_scenario -->|"seeds"| node_scheduler
node_scenario -->|"initializes"| node_network
node_scenario -->|"initializes"| node_faults
node_scenario -->|"records events"| node_event_log
node_faults -->|"draws randomness"| node_scheduler
node_network -->|"queues deliveries"| node_scheduler
node_network -->|"writes events"| node_event_log
node_consensus -->|"sends messages"| node_network
node_consensus -->|"proposes transactions"| node_transaction
node_consensus -->|"creates proposals"| node_block
node_consensus -->|"uses candidate store"| node_block_store
node_consensus -->|"creates votes"| node_vote
node_consensus -->|"aggregates votes"| node_vote_set
node_consensus -->|"executes blocks"| node_executor
node_consensus -->|"finalizes chain"| node_ledger
node_consensus -->|"uses validators"| node_identity
node_router -->|"validates headers"| node_block_validation
node_router -->|"handles blocks"| node_block
node_router -->|"validates votes"| node_vote
node_router -->|"logs rejections"| node_event_log
node_gossip -->|"sends peer data"| node_network
node_gossip -->|"gossips blocks"| node_block
node_gossip -->|"gossips votes"| node_vote
node_gossip -->|"checks vote data"| node_vote_set
node_transaction -->|"verifies signatures"| node_crypto
node_transaction -->|"encodes fields"| node_encoding
node_block -->|"hashes and signs"| node_crypto
node_block -->|"encodes headers"| node_encoding
node_block -->|"checks state hash"| node_state
node_block -->|"validates body transactions"| node_transaction
node_block_validation -->|"validates headers"| node_block
node_block_validation -->|"verifies signatures"| node_crypto
node_vote -->|"signs and verifies"| node_crypto
node_vote -->|"encodes votes"| node_encoding
node_vote_set -->|"aggregates votes"| node_vote
node_executor -->|"updates state"| node_state
node_executor -->|"applies transactions"| node_transaction
node_state -->|"hashes commitment"| node_crypto
node_state -->|"encodes map"| node_encoding
node_ledger -->|"stores headers"| node_block
node_ledger -->|"snapshots state"| node_state
node_legacy_runner -->|"writes events"| node_event_log
node_summary -->|"summarizes run"| node_scenario
node_dashboard_user -->|"opens dashboard"| node_dashboard_app
node_dashboard_app -->|"loads layout"| node_dashboard_layout
node_dashboard_app -->|"registers callbacks"| node_dashboard_callbacks

click node_scenario "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/scenario.py"
click node_scenario_config "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/tree/Main/config"
click node_scheduler "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/scheduler.py"
click node_network "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/network.py"
click node_faults "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/fault_injector.py"
click node_consensus "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/consensus.py"
click node_router "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/router.py"
click node_gossip "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/gossip.py"
click node_transaction "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/transaction.py"
click node_block "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/block.py"
click node_block_validation "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/block_validator.py"
click node_block_store "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/block_store.py"
click node_vote "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/vote.py"
click node_vote_set "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/vote_set.py"
click node_identity "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/identity.py"
click node_executor "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/executor.py"
click node_crypto "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/crypto.py"
click node_encoding "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/encoding.py"
click node_state "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/state.py"
click node_ledger "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/ledger.py"
click node_event_log "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/event_log.py"
click node_summary "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/summary.py"
click node_legacy_runner "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/scenario_runner.py"
click node_dashboard_app "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/dashboard/app.py"
click node_dashboard_layout "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/dashboard/layout.py"
click node_dashboard_callbacks "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/dashboard/callbacks.py"
click node_dashboard_data "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/dashboard/data_loader.py"
click node_dashboard_charts "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/dashboard/charts.py"
click node_dashboard_components "https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/dashboard/components.py"

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_scenario,node_scenario_config,node_scheduler,node_network,node_faults,node_legacy_runner,node_dashboard_user toneBlue
class node_consensus,node_router,node_gossip,node_transaction,node_block,node_block_validation,node_block_store,node_vote,node_vote_set,node_identity,node_executor toneAmber
class node_crypto,node_encoding,node_state toneMint
class node_ledger,node_event_log,node_summary toneRose
class node_dashboard_app,node_dashboard_layout,node_dashboard_callbacks,node_dashboard_data,node_dashboard_charts,node_dashboard_components,node_operator toneIndigo
```

## Components

### Simulation orchestration

- [Scenario runner](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/scenario.py): `src/scenario.py`
- [Scenario configs](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/tree/Main/config): `config`
- [Logical scheduler](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/scheduler.py): `src/scheduler.py`
- [Simulated network](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/network.py): `src/network.py`
- [Fault injector](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/fault_injector.py): `src/fault_injector.py`
- [Legacy runner](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/scenario_runner.py): `src/scenario_runner.py`

### Consensus protocol

- [Consensus state](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/consensus.py): `src/consensus.py`
- [Message router](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/router.py): `src/router.py`
- [Peer gossip](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/gossip.py): `src/gossip.py`
- [Transactions](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/transaction.py): `src/transaction.py`
- [Blocks](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/block.py): `src/block.py`
- [Block validation](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/block_validator.py): `src/block_validator.py`
- [Candidate block store](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/block_store.py): `src/block_store.py`
- [Votes](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/vote.py): `src/vote.py`
- [Vote aggregation](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/vote_set.py): `src/vote_set.py`
- [Validator identities](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/identity.py): `src/identity.py`
- [Block executor](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/executor.py): `src/executor.py`

### Protocol foundations

- [Cryptography](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/crypto.py): `src/crypto.py`
- [Canonical encoding](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/encoding.py): `src/encoding.py`
- [Key-value state](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/state.py): `src/state.py`

### Logs and ledger

- [Finalized ledger](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/ledger.py): `src/ledger.py`
- [Event log](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/event_log.py): `src/event_log.py`
- [Run summary](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/src/summary.py): `src/summary.py`

### Dashboard

- [Dashboard app](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/dashboard/app.py): `dashboard/app.py`
- [Dashboard layout](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/dashboard/layout.py): `dashboard/layout.py`
- [Dashboard callbacks](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/dashboard/callbacks.py): `dashboard/callbacks.py`
- [Log and config loader](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/dashboard/data_loader.py): `dashboard/data_loader.py`
- [Charts](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/dashboard/charts.py): `dashboard/charts.py`
- [UI components](https://github.com/phamnguyengiabao-dev/group2_hcmus_blockchain/blob/Main/dashboard/components.py): `dashboard/components.py`

### Other components

- **Scenario operator**
- **Dashboard user**

## Connections

- Scenario operator → Scenario runner: runs scenario (evidence: `README.md`)
- Scenario configs → Scenario runner: configures (evidence: `README.md`)
- Scenario runner → Logical scheduler: seeds (evidence: `README.md`)
- Scenario runner → Simulated network: initializes (evidence: `README.md`)
- Scenario runner → Fault injector: initializes (evidence: `README.md`)
- Scenario runner → Event log: records events (evidence: `README.md`)
- Fault injector → Logical scheduler: draws randomness (evidence: `src/fault_injector.py`)
- Simulated network → Logical scheduler: queues deliveries (evidence: `src/network.py`)
- Simulated network → Event log: writes events (evidence: `src/network.py`)
- Consensus state → Simulated network: sends messages (evidence: `src/consensus.py`)
- Consensus state → Transactions: proposes transactions (evidence: `src/consensus.py`)
- Consensus state → Blocks: creates proposals (evidence: `src/consensus.py`)
- Consensus state → Candidate block store: uses candidate store (evidence: `src/consensus.py`)
- Consensus state → Votes: creates votes (evidence: `src/consensus.py`)
- Consensus state → Vote aggregation: aggregates votes (evidence: `src/consensus.py`)
- Consensus state → Block executor: executes blocks (evidence: `src/consensus.py`)
- Consensus state → Finalized ledger: finalizes chain (evidence: `src/consensus.py`)
- Consensus state → Validator identities: uses validators (evidence: `src/consensus.py`)
- Message router → Block validation: validates headers (evidence: `src/router.py`)
- Message router → Blocks: handles blocks (evidence: `src/router.py`)
- Message router → Votes: validates votes (evidence: `src/router.py`)
- Message router → Event log: logs rejections (evidence: `src/router.py`)
- Peer gossip → Simulated network: sends peer data (evidence: `src/gossip.py`)
- Peer gossip → Blocks: gossips blocks (evidence: `src/gossip.py`)
- Peer gossip → Votes: gossips votes (evidence: `src/gossip.py`)
- Peer gossip → Vote aggregation: checks vote data (evidence: `src/gossip.py`)
- Transactions → Cryptography: verifies signatures (evidence: `src/transaction.py`)
- Transactions → Canonical encoding: encodes fields (evidence: `src/transaction.py`)
- Blocks → Cryptography: hashes and signs (evidence: `src/block.py`)
- Blocks → Canonical encoding: encodes headers (evidence: `src/block.py`)
- Blocks → Key-value state: checks state hash (evidence: `src/block.py`)
- Blocks → Transactions: validates body transactions (evidence: `src/block.py`)
- Block validation → Blocks: validates headers (evidence: `src/block_validator.py`)
- Block validation → Cryptography: verifies signatures (evidence: `src/block_validator.py`)
- Votes → Cryptography: signs and verifies (evidence: `src/vote.py`)
- Votes → Canonical encoding: encodes votes (evidence: `src/vote.py`)
- Vote aggregation → Votes: aggregates votes (evidence: `src/vote_set.py`)
- Block executor → Key-value state: updates state (evidence: `src/executor.py`)
- Block executor → Transactions: applies transactions (evidence: `src/executor.py`)
- Key-value state → Cryptography: hashes commitment (evidence: `src/state.py`)
- Key-value state → Canonical encoding: encodes map (evidence: `src/state.py`)
- Finalized ledger → Blocks: stores headers (evidence: `src/ledger.py`)
- Finalized ledger → Key-value state: snapshots state (evidence: `src/ledger.py`)
- Legacy runner → Event log: writes events (evidence: `src/scenario_runner.py`)
- Run summary → Scenario runner: summarizes run (evidence: `src/summary.py`)
- Dashboard user → Dashboard app: opens dashboard (evidence: `dashboard/app.py`)
- Dashboard app → Dashboard layout: loads layout (evidence: `dashboard/app.py`)
- Dashboard app → Dashboard callbacks: registers callbacks (evidence: `dashboard/app.py`)
