How 15dkatz/python-blockchain-tutorial works
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: blockchain.py Chain core · __main__.py App entry · App.js React app · tests Backend tests
Components 19
Backend
Python service, domain model, networking, and scripts
- App entry · Backend runtime entrypoint and API boundary
backend/app/__main__.py - Config · Runtime configuration and environment flags
backend/config.py - Block · Single block structure and block-level validation
backend/blockchain/block.py - Chain core · Chain management, validation, and block addition
backend/blockchain/blockchain.py - Wallet · Key-based ownership and transaction creation
backend/wallet/wallet.py - Transaction · Transaction data and signatures
backend/wallet/transaction.py - Tx pool · Pending transactions awaiting mining
backend/wallet/transaction_pool.py - Pub/Sub · PubNub-backed propagation of chain and transaction updates
backend/pubsub.py
Frontend
React UI that reads chain state and submits transactions
- React app · Browser application that drives the user interface
frontend/src/components/App.js - Blockchain UI · Displays blocks and chain state
frontend/src/components/Blockchain.js - Block view · Renders an individual block
frontend/src/components/Block.js - Pool view · Shows pending transactions
frontend/src/components/TransactionPool.js - Transaction view · Renders a transaction
frontend/src/components/Transaction.js - Send tx · Form for creating and submitting transactions
frontend/src/components/ConductTransaction.js - UI config · Frontend backend endpoint configuration
frontend/src/config.js
Support
Environment, utilities, and tests around core rules
- Hashing · Hash primitive used by block and chain logic
backend/util/crypto_hash.py - Hex/bin · Hex to binary conversion for proof-of-work checks
backend/util/hex_to_binary.py - Backend tests · Domain tests for blockchain, wallet, and utilities
backend/tests - Scripts · Operational and diagnostic backend scripts
backend/scripts
Connections 24
- 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