Module Overview

Bunkercoin is architected as a modular system where each Rust module encapsulates specific functionality. This design enables independent development, testing, and potential replacement of components without affecting the overall system stability.

Module Dependency Graph

Module Dependencies:

main.rs
├── blockchain.rs ──────┐
│   ├── block.rs        │
│   ├── transaction.rs  │
│   ├── vdf.rs          │
│   └── web.rs ─────────┼─── Global Event System
├── wallet.rs           │
│   └── transaction.rs  │
├── network.rs ─────────┤
│   ├── block.rs        │
│   └── transaction.rs  │
└── web.rs ─────────────┘
    ├── blockchain.rs
    ├── block.rs
    └── transaction.rs

Core Modules

Module

main.rs - Application Entry Point

Target

main.rs - CLI Interface

Module

blockchain.rs - Core Blockchain Logic

Target

blockchain.rs - Chain Logic

Module

web.rs - HTTP Interface & SSE

Target

web.rs - HTTP Interface

Module

wallet.rs - Key Management

Target

wallet.rs - Key Management

Module

transaction.rs - Transaction Structure

Target

transaction.rs - Transactions

Module

block.rs - Block Structure

Target

block.rs - Block Structure

Module

network.rs - TCP P2P Protocol

Target

network.rs - P2P Protocol

Module

vdf.rs - Verifiable Delay Function

Target

vdf.rs - Proof of Work

Module Interaction Patterns

Data Flow Patterns

• Transaction Creation: wallet.rs → transaction.rs → blockchain.rs

• Block Mining: blockchain.rs → vdf.rs → block.rs → web.rs

• Network Sync: main.rs → web.rs → blockchain.rs

• P2P Communication: network.rs ↔ blockchain.rs

Event Broadcasting

• Global Events: web.rs provides system-wide event channel

• Mining Updates: blockchain.rs → web.rs → SSE clients

• Transaction Events: All modules → web.rs broadcast

• Error Reporting: Distributed logging via web.rs

Architectural Principles

Separation of Concerns

Each module has a clearly defined responsibility. Cryptographic operations are isolated in wallet.rs and transaction.rs, network communication is handled by web.rs and network.rs, and core logic resides in blockchain.rs.

Minimal Dependencies

Cross-module dependencies are kept to the absolute minimum. The lib.rs file shows the complete module structure, and most modules only depend on shared data structures rather than complex functionality.

Radio-Optimized Design

All modules are designed with radio communication constraints in mind. Data structures are compact, operations are deterministic, and timing is predictable to enable reliable HF radio propagation.

Thread Safety

Shared state is protected by Arc wrappers, enabling safe concurrent access across async tasks. This allows the HTTP server, mining loop, and peer synchronization to operate simultaneously.

Development Guidelines

Adding New Features

• Follow existing module patterns

• Minimize cross-module dependencies

• Use web.rs for event broadcasting

• Maintain deterministic behavior

Testing Strategy

• Unit test individual modules

• Integration test module interactions

• Verify radio-compatible behavior

• Test network partition scenarios