# 15dkatz/python-blockchain-tutorial architecture

> Architecture diagram of the GitHub repository 15dkatz/python-blockchain-tutorial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/15dkatz/python-blockchain-tutorial
- Repository: https://github.com/15dkatz/python-blockchain-tutorial

## Overview

1. **High-level shape**
   - This repo is a two-tier blockchain/cryptocurrency application:
     - a **Python backend** that owns the blockchain, wallets, transactions, mining, and peer synchronization
     - a **React frontend** that provides the user interface for browsing the chain and submitting transactions

2. **Backend entrypoint and runtime**
   - The backend starts from `backend/app/__main__.py`.
   - It is run as a Python module, and the README shows it can operate in different modes via environment flags such as `SEED_DATA` and `PEER`.
   - `backend/config.py` and `backend/env.example` indicate that runtime behavior is environment-driven, especially for network/pub-sub settings.

3. **Blockchain core domain**
   - `backend/blockchain/block.py` and `backend/blockchain/blockchain.py` implement the main ledger model.
   - This is the central data structure of the system: blocks contain transactions, and the blockchain module manages chain state, validation, and block addition.
   - The `backend/tests/blockchain/` suite shows this is a separately testable subsystem with strong domain boundaries.

4. **Cryptocurrency / wallet subsystem**
   - `backend/wallet/wallet.py`, `transaction.py`, and `transaction_pool.py` form the cryptocurrency layer on top of the chain.
   - The wallet side is responsible for key-based ownership, transaction creation, and maintaining a pool of pending transactions before they are mined into blocks.
   - This subsystem is distinct from the raw blockchain ledger and sits between user intent and chain inclusion.

5. **Shared utilities**
   - `backend/util/crypto_hash.py` and `hex_to_binary.py` are low-level helpers used by the blockchain logic.
   - These utilities support hashing, proof-of-work style validation, and binary/hex conversions, which are core to block identification and mining rules.
   - Their dedicated tests under `backend/tests/util/` suggest they are treated as foundational primitives.

6. **Networking and peer synchronization**
   - `backend/pubsub.py` is the main peer-to-peer coordination layer.
   - The README explicitly states the system uses **PubNub** for real-time communication between blockchain nodes, so this repo is not just a local single-process chain; it supports a distributed peer network.
   - `PUBNUB_CONFIG.md` and the `PEER=True` runtime mode indicate that peers broadcast chain/transaction updates through PubNub rather than a custom socket server.

7. **Backend API surface**
   - The backend is also exposed as an HTTP service, most likely through Flask as indicated by the README.
   - The `backend/app` package is the API/application boundary that connects external clients to blockchain state and wallet actions.
   - In architecture terms, this is the boundary between UI/clients and the domain logic layers.

8. **Frontend application**
   - The `frontend/` directory is a React application with components for:
     - `Blockchain`
     - `Block`
     - `TransactionPool`
     - `Transaction`
     - `ConductTransaction`
   - This suggests the UI is split into read views for chain state and write views for creating transactions.
   - `frontend/src/config.js` likely points the UI to the backend API endpoint.

9. **Frontend-to-backend data flow**
   - The frontend is not the source of truth; it consumes backend state over HTTP and triggers backend actions such as transaction creation or chain inspection.
   - The backend remains authoritative for validating and propagating blocks/transactions.
   - Because peer sync is handled separately via PubNub, the frontend likely talks only to one local backend instance, while that backend participates in the wider network.

10. **Testing strategy**
   - The repository has a comprehensive `backend/tests/` tree covering blockchain, wallet, and utility code.
   - This indicates the architecture is organized around testable domain modules rather than a monolithic app.
   - There are also backend scripts under `backend/scripts/` for operational or diagnostic tasks.

11. **Operational tooling and environment**
   - `blockchain-env/` is a checked-in Python virtual environment directory, showing the project was developed with an isolated Python runtime.
   - `requirements.txt` defines backend dependencies, while `frontend/package.json` and `package-lock.json` define the Node/React toolchain.
   - `backend/scripts/average_block_rate.py` suggests some support tooling around mining performance or chain timing.

12. **Important architectural boundaries for a diagram**
   - **UI boundary:** React frontend
   - **Service boundary:** Flask/Python backend API
   - **Domain boundary:** blockchain + wallet/transaction model
   - **Distribution boundary:** PubNub pub/sub peer network
   - **Config boundary:** environment variables and `.env`-driven runtime settings
   - **Test/utility boundary:** isolated helpers and unit tests around core rules

13. **What is authoritative where**
   - Blockchain state and transaction validity live in the backend.
   - Peer replication is event-driven through PubNub, not directly by the frontend.
   - The frontend is a presentation and interaction layer, not a consensus participant.

Main entry points: [`backend/blockchain/blockchain.py`](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/blockchain/blockchain.py) (Chain core), [`backend/app/__main__.py`](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/app/__main__.py) (App entry), [`frontend/src/components/App.js`](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/components/App.js) (React app), [`backend/tests`](https://github.com/15dkatz/python-blockchain-tutorial/tree/master/backend/tests) (Backend tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_app["App entry<br/>Python module<br/>[__main__.py]"]
  node_backend_config["Config<br/>env-driven settings<br/>[config.py]"]
  node_block_model["Block<br/>ledger record<br/>[block.py]"]
  node_blockchain_core[("Chain core<br/>ledger state<br/>[blockchain.py]")]
  node_wallet_core["Wallet<br/>keyed account<br/>[wallet.py]"]
  node_transaction_model["Transaction<br/>transfer model<br/>[transaction.py]"]
  node_tx_pool["Tx pool<br/>pending queue"]
  node_pubsub(("Pub/Sub<br/>peer sync<br/>[pubsub.py]"))
end

subgraph group_frontend["Frontend"]
  node_frontend_app["React app<br/>UI shell<br/>[App.js]"]
  node_ui_chain["Blockchain UI<br/>read view<br/>[Blockchain.js]"]
  node_ui_block["Block view<br/>read view<br/>[Block.js]"]
  node_ui_pool["Pool view<br/>read view<br/>[TransactionPool.js]"]
  node_ui_tx["Transaction view<br/>read view<br/>[Transaction.js]"]
  node_ui_conduct["Send tx<br/>write view"]
  node_frontend_config["UI config<br/>api endpoint config<br/>[config.js]"]
end

subgraph group_support["Support"]
  node_crypto_hash["Hashing<br/>crypto util<br/>[crypto_hash.py]"]
  node_hex_binary["Hex/bin<br/>encoding util<br/>[hex_to_binary.py]"]
  node_backend_tests["Backend tests<br/>test suite"]
  node_backend_scripts["Scripts<br/>ops tools"]
end

node_backend_app -->|"loads"| node_backend_config
node_backend_app -->|"serves"| node_blockchain_core
node_backend_app -->|"serves"| node_wallet_core
node_backend_app -->|"joins"| node_pubsub
node_blockchain_core -->|"uses"| node_block_model
node_blockchain_core -->|"hashes"| node_crypto_hash
node_blockchain_core -->|"checks"| node_hex_binary
node_wallet_core -->|"creates"| node_transaction_model
node_wallet_core -->|"queues"| node_tx_pool
node_tx_pool -->|"stores"| node_transaction_model
node_pubsub -->|"broadcasts"| node_blockchain_core
node_pubsub -->|"broadcasts"| node_tx_pool
node_frontend_app -->|"configures"| node_frontend_config
node_frontend_app -->|"composes"| node_ui_chain
node_frontend_app -->|"composes"| node_ui_pool
node_frontend_app -->|"composes"| node_ui_conduct
node_ui_chain -->|"renders"| node_ui_block
node_ui_pool -->|"renders"| node_ui_tx
node_ui_conduct -.->|"submits"| node_transaction_model
node_backend_scripts -.->|"inspects"| node_blockchain_core
node_backend_tests -.->|"verifies"| node_blockchain_core
node_backend_tests -.->|"verifies"| node_wallet_core
node_backend_tests -.->|"verifies"| node_crypto_hash
node_backend_tests -.->|"verifies"| node_hex_binary

click node_backend_app "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/app/__main__.py"
click node_backend_config "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/config.py"
click node_block_model "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/blockchain/block.py"
click node_blockchain_core "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/blockchain/blockchain.py"
click node_wallet_core "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/wallet/wallet.py"
click node_transaction_model "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/wallet/transaction.py"
click node_tx_pool "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/wallet/transaction_pool.py"
click node_pubsub "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/pubsub.py"
click node_crypto_hash "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/util/crypto_hash.py"
click node_hex_binary "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/util/hex_to_binary.py"
click node_frontend_app "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/components/App.js"
click node_ui_chain "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/components/Blockchain.js"
click node_ui_block "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/components/Block.js"
click node_ui_pool "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/components/TransactionPool.js"
click node_ui_tx "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/components/Transaction.js"
click node_ui_conduct "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/components/ConductTransaction.js"
click node_frontend_config "https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/config.js"
click node_backend_tests "https://github.com/15dkatz/python-blockchain-tutorial/tree/master/backend/tests"
click node_backend_scripts "https://github.com/15dkatz/python-blockchain-tutorial/tree/master/backend/scripts"

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_backend_app,node_backend_config,node_block_model,node_blockchain_core,node_wallet_core,node_transaction_model,node_tx_pool,node_pubsub toneBlue
class node_frontend_app,node_ui_chain,node_ui_block,node_ui_pool,node_ui_tx,node_ui_conduct,node_frontend_config toneAmber
class node_crypto_hash,node_hex_binary,node_backend_tests,node_backend_scripts toneMint
```

## Components

### Backend

Python service, domain model, networking, and scripts

- [App entry](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/app/__main__.py): Python module · Backend runtime entrypoint and API boundary · `backend/app/__main__.py`
- [Config](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/config.py): env-driven settings · Runtime configuration and environment flags · `backend/config.py`
- [Block](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/blockchain/block.py): ledger record · Single block structure and block-level validation · `backend/blockchain/block.py`
- [Chain core](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/blockchain/blockchain.py): ledger state · Chain management, validation, and block addition · `backend/blockchain/blockchain.py`
- [Wallet](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/wallet/wallet.py): keyed account · Key-based ownership and transaction creation · `backend/wallet/wallet.py`
- [Transaction](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/wallet/transaction.py): transfer model · Transaction data and signatures · `backend/wallet/transaction.py`
- [Tx pool](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/wallet/transaction_pool.py): pending queue · Pending transactions awaiting mining · `backend/wallet/transaction_pool.py`
- [Pub/Sub](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/pubsub.py): peer sync · PubNub-backed propagation of chain and transaction updates · `backend/pubsub.py`

### Frontend

React UI that reads chain state and submits transactions

- [React app](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/components/App.js): UI shell · Browser application that drives the user interface · `frontend/src/components/App.js`
- [Blockchain UI](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/components/Blockchain.js): read view · Displays blocks and chain state · `frontend/src/components/Blockchain.js`
- [Block view](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/components/Block.js): read view · Renders an individual block · `frontend/src/components/Block.js`
- [Pool view](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/components/TransactionPool.js): read view · Shows pending transactions · `frontend/src/components/TransactionPool.js`
- [Transaction view](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/components/Transaction.js): read view · Renders a transaction · `frontend/src/components/Transaction.js`
- [Send tx](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/components/ConductTransaction.js): write view · Form for creating and submitting transactions · `frontend/src/components/ConductTransaction.js`
- [UI config](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/frontend/src/config.js): api endpoint config · Frontend backend endpoint configuration · `frontend/src/config.js`

### Support

Environment, utilities, and tests around core rules

- [Hashing](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/util/crypto_hash.py): crypto util · Hash primitive used by block and chain logic · `backend/util/crypto_hash.py`
- [Hex/bin](https://github.com/15dkatz/python-blockchain-tutorial/blob/master/backend/util/hex_to_binary.py): encoding util · Hex to binary conversion for proof-of-work checks · `backend/util/hex_to_binary.py`
- [Backend tests](https://github.com/15dkatz/python-blockchain-tutorial/tree/master/backend/tests): test suite · Domain tests for blockchain, wallet, and utilities · `backend/tests`
- [Scripts](https://github.com/15dkatz/python-blockchain-tutorial/tree/master/backend/scripts): ops tools · Operational and diagnostic backend scripts · `backend/scripts`

## Connections

- App entry → Config: loads · Reads runtime flags and service settings
- App entry → Chain core: serves · Exposes chain operations through the application boundary
- App entry → Wallet: serves · Handles wallet and transaction actions
- App entry → Pub/Sub: joins · Participates in peer synchronization when running as a peer
- Chain core → Block: uses · Builds and validates chains from blocks
- Chain core → Hashing: hashes · Derives block identity and validation inputs
- Chain core → Hex/bin: checks · Supports proof-of-work style validation
- Wallet → Transaction: creates · Creates signed transactions from wallet state
- Wallet → Tx pool: queues · Places new transactions into the pending pool
- Tx pool → Transaction: stores · Holds pending transaction objects
- Pub/Sub → Chain core: broadcasts · Propagates chain updates to peers
- Pub/Sub → Tx pool: broadcasts · Propagates pending transactions to peers
- React app → UI config: configures · Uses API endpoint settings
- React app → Blockchain UI: composes · Main UI includes chain browsing
- React app → Pool view: composes · Main UI includes pending transaction views
- React app → Send tx: composes · Main UI includes transaction submission flow
- Blockchain UI → Block view: renders · Chain view is built from block views
- Pool view → Transaction view: renders · Pool view is built from transaction views
- Send tx → Transaction: submits · Creates transaction payloads for backend submission
- Scripts → Chain core: inspects · Operational scripts interact with chain state
- Backend tests → Chain core: verifies · Tests the blockchain domain rules
- Backend tests → Wallet: verifies · Tests wallet and transaction behavior
- Backend tests → Hashing: verifies · Tests shared hashing utility
- Backend tests → Hex/bin: verifies · Tests encoding utility
