Skip to content
This repository was archived by the owner on Aug 1, 2023. It is now read-only.

Commit d345e2a

Browse files
authored
[GH-24] Add understandable documentation for non-developers (#81)
* Initial write up for the document for non-developers * Fix grammar * Fix typo * Add diagrams * Replace interface with layer * Add more description * Add diagram
1 parent fd48ab2 commit d345e2a

File tree

1 file changed

+76
-0
lines changed

1 file changed

+76
-0
lines changed

docs/Document.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Overview
2+
3+
`cardano-shell` is an thin layer which brings all the other modules working
4+
together and makes sure that they have the required resources
5+
(configuration, exception handling, ...).
6+
7+
## Cardano-node to operate as an peer
8+
9+
For cardano-node to operate as an peer, various **features** are required:
10+
11+
* Logging, to let the user know what's going on
12+
* Block validation
13+
* Managing blockchain/stake
14+
* Communicating with other peers
15+
* Submitting transaction
16+
* Providing interface/API so that the user can interact with the node
17+
18+
and so on. Because of this, IOHK currently has multiple development teams,
19+
each of which is responsible for developing specific features.
20+
21+
* [blockchain layer](https://github.com/input-output-hk/cardano-ledger)
22+
* [ledger layer](https://github.com/input-output-hk/cardano-ledger)
23+
* [logging/monitoring layer](https://github.com/input-output-hk/iohk-monitoring-framework)
24+
* [network layer](https://github.com/input-output-hk/ouroboros-network)
25+
* [wallet backend layer](https://github.com/input-output-hk/cardano-wallet)
26+
27+
### Bringing features together
28+
29+
The thing to note is that all these features are being worked on **seperate**
30+
repository.
31+
32+
![scattered-modules](https://user-images.githubusercontent.com/15665039/55607001-dbcf3e00-57b5-11e9-89bf-9ed403c4e8e6.jpg)
33+
34+
We need these modules working together to act as a node. This is where
35+
`cardano-shell` comes in. The shell will act as a **glue** of these features,
36+
providing required resources/configurations to each of these features as well as
37+
resolving its dependencies.
38+
39+
![shell-diagram](https://user-images.githubusercontent.com/6264437/47286815-88df4100-d5f0-11e8-92a7-c807b6d3b47a.jpg)
40+
41+
## Resolving dependencies between the features
42+
43+
There are **dependencies** between the features meaning some of the features
44+
depend on others. For example,
45+
46+
* `networking` feature requires `logging` and `monitoring`
47+
* `blockchain` feature `logging` and `networking`
48+
49+
and so on.
50+
51+
The shell will resolve these dependencies by having each of the features to
52+
produce a `layer` and distributing them to other features that depend on it.
53+
54+
### Layer
55+
56+
To put it simple, **a layer is a record of functions that each feature generates when initialized**.
57+
For example, logging feature will produce logging layer when initialized.
58+
The logging layer will have a list of functions related to logging such as
59+
`logInfo`, `logDebug` which the other features can use.
60+
61+
![layer](https://user-images.githubusercontent.com/15665039/55375129-e1bee800-5545-11e9-82c0-f7bef87deaf3.jpg)
62+
63+
Dependencies between the features are resolved by passing these layers.
64+
65+
- If `networking` feature requires `logging`, then it will have logging
66+
layer as a dependency when initializing.
67+
68+
![network](https://user-images.githubusercontent.com/15665039/55375015-7f65e780-5545-11e9-9fd8-ca2d37d7cc28.jpg)
69+
70+
- If `blockchain` feature requires `logging` and `network`, then shell will
71+
provide those layers as dependencies.
72+
73+
![blockchain](https://user-images.githubusercontent.com/15665039/55375281-8a6d4780-5546-11e9-9240-21d9ca8cbc46.jpg)
74+
75+
Layers are defined in such a way that it can be **stubbed**. This will
76+
allow the developer to write test cases on each features with ease.

0 commit comments

Comments
 (0)