From 1d195959d8241aeee8e95978b638269224aa7f52 Mon Sep 17 00:00:00 2001
From: Daniel Sanchez <sanchez.quiros.daniel@gmail.com>
Date: Fri, 10 Feb 2023 17:07:04 +0100
Subject: [PATCH] Add services and project information to project README (#72)

* Add services and project information to project README

* Better phrased nomos services
---
 README.md | 45 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 44 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index aa138f12..df3e046d 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,52 @@
 # nomos-research
 Nomos blockchain node mvp
 
+
+## Project structure
+
+- `nomos-core`: Nomos core is the collection of essential structures for the Nomos mvp and experimental nodes.
+- `nomos-services`: Nomos services is the collection of components that are used as building blocks of the Nomos node prototype and the experimental nodes.
+  - consensus
+  - log
+  - http
+  - mempool
+  - network
+  - metrics
+- `nodes`: Nomos nodes is the collection of nodes that are used to run the Nomos mvp and experimental nodes.
+  - `nomos-node`: main implementation of the Nomos mvp node.
+  - `mockpool-node`: node with single mempool service, used to measure transaction dissemination.
+
+
+## Services
+
+The Nomos node uses `Overwatch` as its main internal framework. This means that services request communication channels 
+to other services to interchange information through a specified messaging API.
+
+### Service architecture
+
+Most of the services are implemented with the same idea behind. There is a front layer responsible for handling the `Overwatch` service
+and a back layer that implement the actual service logic.
+
+This allows us to easily replace components as needed in a type level system. In any case, a node can be setup in a declarative way composing the types.
+For example:
+
+```rust
+...
+#[derive(Services)]
+struct MockPoolNode {
+    logging: ServiceHandle<Logger>,
+    network: ServiceHandle<NetworkService<Waku>>,
+    mockpool: ServiceHandle<MempoolService<WakuAdapter<Tx>, MockPool<TxId, Tx>>>,
+    http: ServiceHandle<HttpService<AxumBackend>>,
+    bridges: ServiceHandle<HttpBridgeService>,
+}
+```
+
+
+
 ## Docker
 
-To build and run a docker container with nomos node run:
+To build and run a docker container with Nomos node run:
 
 ```bash
 docker build -t nomos .