Augmented node template docs (#6721)

substrate/bin/node-template/README.md

@@ -8,8 +8,8 @@ Follow these steps to prepare a local Substrate development environment :hammer_
 
 ### Simple Setup
 
-Install all the required dependencies with a single command (be patient, this can take up
-to 30 minutes).
+Install all the required dependencies with a single command (be patient, this can take up to 30
+minutes).
 
 ```bash
 curl https://getsubstrate.io -sSf | bash -s -- --fast
@@ -17,7 +17,8 @@ curl https://getsubstrate.io -sSf | bash -s -- --fast
 
 ### Manual Setup
 
-Find manual setup instructions at the [Substrate Developer Hub](https://substrate.dev/docs/en/knowledgebase/getting-started/#manual-installation).
+Find manual setup instructions at the
+[Substrate Developer Hub](https://substrate.dev/docs/en/knowledgebase/getting-started/#manual-installation).
 
 ### Build
 
@@ -54,8 +55,8 @@ RUST_LOG=debug RUST_BACKTRACE=1 ./target/release/node-template -lruntime=debug -
 ### Multi-Node Local Testnet
 
 To see the multi-node consensus algorithm in action, run a local testnet with two validator nodes,
-Alice and Bob, that have been [configured](/bin/node-template/node/src/chain_spec.rs) as the
-initial authorities of the `local` testnet chain and endowed with testnet units.
+Alice and Bob, that have been [configured](/bin/node-template/node/src/chain_spec.rs) as the initial
+authorities of the `local` testnet chain and endowed with testnet units.
 
 Note: this will require two terminal sessions (one for each node).
 
@@ -92,6 +93,91 @@ cargo run -- \
 
 Execute `cargo run -- --help` to learn more about the template node's CLI options.
 
+## Template Structure
+
+A Substrate project such as this consists of a number of components that are spread across a few
+directories.
+
+### Node
+
+A blockchain node is an application that allows users to participate in a blockchain network.
+Substrate-based blockchain nodes expose a number of capabilities:
+
+-   Networking: Substrate nodes use the [`libp2p`](https://libp2p.io/) networking stack to allow the
+    nodes in the network to communicate with one another.
+-   Consensus: Blockchains must have a way to come to
+    [consensus](https://substrate.dev/docs/en/knowledgebase/advanced/consensus) on the state of the
+    network. Substrate makes it possible to supply custom consensus engines and also ships with
+    several consensus mechanisms that have been built on top of Web3 Foundation research.
+-   RPC Server: A remote procedure call (RPC) server is used to interact with Substrate nodes.
+
+There are several files in the `node` directory - take special note of the following:
+
+-   [`chain_spec.rs`](./node/src/chain_spec.rs): A
+    [chain specification](https://substrate.dev/docs/en/knowledgebase/integrate/chain-spec) is a
+    source code file that defines a Substrate chain's initial (genesis) state. Chain specifications
+    are useful for development and testing, and critical when architecting the launch of a
+    production chain. Take note of the `development_config` and `testnet_genesis` functions, which
+    are used to define the genesis state for the local development chain configuration. These
+    functions identify some
+    [well-known accounts](https://substrate.dev/docs/en/knowledgebase/integrate/subkey#well-known-keys)
+    and use them to configure the blockchain's initial state.
+-   [`service.rs`](./node/src/service.rs): This file defines the node implementation. Take note of
+    the libraries that this file imports and the names of the functions it invokes. In particular,
+    there are references to consensus-related topics, such as the
+    [longest chain rule](https://substrate.dev/docs/en/knowledgebase/advanced/consensus#longest-chain-rule),
+    the [Aura](https://substrate.dev/docs/en/knowledgebase/advanced/consensus#aura) block authoring
+    mechanism and the
+    [GRANDPA](https://substrate.dev/docs/en/knowledgebase/advanced/consensus#grandpa) finality
+    gadget.
+
+After the node has been [built](#build), refer to the embedded documentation to learn more about the
+capabilities and configuration parameters that it exposes:
+
+```shell
+./target/release/node-template --help
+```
+
+### Runtime
+
+The Substrate project in this repository uses the
+[FRAME](https://substrate.dev/docs/en/knowledgebase/runtime/frame) framework to construct a
+blockchain runtime. FRAME allows runtime developers to declare domain-specific logic in modules
+called "pallets". At the heart of FRAME is a helpful
+[macro language](https://substrate.dev/docs/en/knowledgebase/runtime/macros) that makes it easy to
+create pallets and flexibly compose them to create blockchains that can address a variety of needs.
+
+Review the [FRAME runtime implementation](./runtime/src/lib.rs) included in this template and note
+the following:
+
+-   This file configures several pallets to include in the runtime. Each pallet configuration is
+    defined by a code block that begins with `impl $PALLET_NAME::Trait for Runtime`.
+-   The pallets are composed into a single runtime by way of the
+    [`construct_runtime!`](https://crates.parity.io/frame_support/macro.construct_runtime.html)
+    macro, which is part of the core
+    [FRAME Support](https://substrate.dev/docs/en/knowledgebase/runtime/frame#support-library)
+    library.
+
+### Pallets
+
+The runtime in this project is constructed using many FRAME pallets that ship with the
+[core Substrate repository](https://github.com/paritytech/substrate/tree/master/frame) and a
+template pallet that is [defined in the `pallets`](./pallets/template/src/lib.rs) directory.
+
+A FRAME pallet is compromised of a number of blockchain primitives:
+
+-   Storage: FRAME defines a rich set of powerful
+    [storage abstractions](https://substrate.dev/docs/en/knowledgebase/runtime/storage) that makes
+    it easy to use Substrate's efficient key-value database to manage the evolving state of a
+    blockchain.
+-   Dispatchables: FRAME pallets define special types of functions that can be invoked (dispatched)
+    from outside of the runtime in order to update its state.
+-   Events: Substrate uses [events](https://substrate.dev/docs/en/knowledgebase/runtime/events) to
+    notify users of important changes in the runtime.
+-   Errors: When a dispatchable fails, it returns an error.
+-   Trait: The `Trait` configuration interface is used to define the types and parameters upon which
+    a FRAME pallet depends.
+
 ## Generate a Custom Node Template
 
 Generate a Substrate node template based on a particular commit by running the following commands: