= Structure
:Author: Substrate developers
:Revision: 0.3.0
:toc:
:sectnums:


== Overview

Substrate is split into multiple levels with increasing opinion and decreasing flexibility:

* primitives
* client
* FRAME (formerly `srml`)

Putting all these components together we have:

* Integration Tests
* Node
* Node template
* Subkey

=== Runtime

* _found in_: `/primitives`
* _crates prefix_: `sp-`
* _constraints_:
** must be `[no_std]`
** crates may not (dev-)depend on crates in other subfolders of this repo

In the lowest level, Substrate defines primitives, interfaces and traits to implement any on-chain Substrate transition system and its interactions with the outside world. This is the lowest level of abstraction and opinion that everything else builds upon.

=== Client

* _found in_: `/client`
* _crates prefix_: `sc-`
* _constraints_:
** crates may not (dev-)depend on any `frame-`-crates

In the client you can find a set of crates to construct the outer substrate-node, implementing outer runtime interfaces, thus it depends on `runtime`. It provides the outer building blocks like transaction queue, networking layer, database backend, full* and light-client support.

=== FRAME (formerly `srml`)

* _found in_: `/frame`
* _crates prefix_: `frame-` and `pallet-`
* _constraints_:
** all crates that go on chain must be `[no_std]`
** must not (dev-)depend on anything in `/client`

FRAME is a set of modules that implement specific transition functions and features one might want to have in their runtime.

_Pallets_ are individual modules within _FRAME._ These are containers that host domain-specific logic. They have the `pallet-` prefix. For example, `pallet-staking` contains logic for staking tokens.

There are a few crates with the `frame-` prefix. These do not contain domain-specific logic. Rather, they are the main FRAME support infrastructure. These are:

- Executive
- Metadata
- Support
- System
- Utility

=== Integration Tests

* _found in_: `/test`
* _crates prefix_: `substrate-test`
* _constraints_:
** only helpers may be published
** purely testing crates must be `publish = false`

All tests that have to pull (dev)-dependencies out of their subtree and would thus break the dependency rules are considered integration tests and should be stored in here. Only helper-crates in here shall be published, everything else is expected to be non-publish.

=== Binaries and template

* _found in_: `/bin`

We also provide some binaries pulling from the components creating full applications.

==== Node

* _found in_: `/bin/node`

The default (testing) application pulling together our recommended setup of substrate-client with a wasm-contracts-supporting frame-runtime.  The node pulls it all together, constructs the (upgradable) runtime, and wires up the client around it. You can find an example client, which includes a full wasm-contracts chain in  `node`. This is also what is being built and run if you do `cargo run`.

==== Node Template

* _found in_: `/bin/node-template`

We also provide a template to get you started building your own node.

==== Utils

* _found in_: `/bin/utils`

- **subkey**
  Subkey is a client library to generate keys and sign transactions to send to a substrate node.
- **chain-spec-builder**
  The chain spec builder builds a chain specification that includes a Substrate runtime compiled as WASM. To ensure proper functioning of the included runtime compile (or run) the chain spec builder binary in `--release` mode.

== Internal Dependency Tree

[ditaa]
....
+---------------+       +----------------+
|               |       |                |
|    runtime    +<------+   frame        |
|               |       |                |
+------+-----+--+       +-------------+--+
       ^     ^                        ^
       |     +----------------+       |
       |                      |       |
+------+--------+             |       |
|               |             |       |
|   client      |          +--+-------+--------+
|               +<---------+                   |
+---------------+          |                   |
                           |   test  /bin/*    |
                           |                   |
                           |                   |
                           +-------------------+

....