Add basic documentation to get started

README.md

@@ -1,6 +1,12 @@
 # Wanda
 
-**TODO: Add description**
+A service responsible to orchestrate Checks executions on a target infrastructure.
+
+- [Installation](#installation)
+- [Developing Checks](#developing-checks)
+  - [Infrastructure](#infrastructure)
+  - [Testing Executions](#testing-executions)
+  - [Adding new Checks](#adding-new-checks)
 
 ## Installation
 
@@ -19,3 +25,98 @@ Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_do
 and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
 be found at <https://hexdocs.pm/wanda>.
 
+## Developing Checks
+
+Wanda architecture aims to simplify [testing Checks Executions](#testing-executions) and [adding new ones](#adding-new-checks). 
+
+### Infrastructure
+
+A docker-compose setup is provided to enable seamless experience with the system.
+
+#### Starting a local environment
+Start the required infrastructure (see [docker-compose.checks.yaml](./docker-compose.checks.yaml))
+
+```bash
+$ docker-compose -f docker-compose.checks.yaml up -d
+```
+
+This starts:
+- wanda, the engine
+- a database where execution informations are stored
+- a message broker for infromation exchange between the targets and wanda
+
+Wanda is exposed on port `4000` and the API documentation is available at http://localhost:4000/swaggerui
+
+![OpenAPI Spec](./guides/img/api_spec.png)
+
+**Note** that the [message broker](https://www.rabbitmq.com/) **must** be reachable by wanda and all the targets.
+
+### Testing Executions
+
+With a runnig setup it is possible to easily test Checks and their Execution by:
+- consulting the catalog
+- triggering a Checks Execution
+- checking up the state of the triggered execution
+
+#### **Consulting the catalog**
+
+Available Checks are part of the **Catalog**, and they can be retrieved by accessing the dedicated API
+```bash
+curl -X 'GET' \
+  'http://localhost:4000/api/checks/catalog' \
+  -H 'accept: application/json'
+```
+
+#### **Triggering a Checks Execution**
+
+A Checks Execution can be triggered by calling the Start Execution endpoint, as follows
+
+```bash
+curl--request POST 'http://localhost:4000/api/checks/executions/start' \
+--header 'accept: application/json' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+  "env": {
+    "provider": "azure"
+  },
+  "execution_id": "205e326d-0c25-4f4b-9976-43f9ba1c86d3",
+  "group_id": "3dff9d03-4adf-453e-9513-8533e221bb12",
+  "targets": [
+    {
+      "agent_id": "a644919a-d953-43d4-bd57-7e0bb96ee894",
+      "checks": [
+        "156F64"
+      ]
+    }
+  ]
+}'
+```
+
+In order to get the detailed information for an execution see [Getting Execution details](#getting-execution-details).
+
+> Please note that execution is _eventually started_, meaning that a successful response to the previous API call does not guarantee that the execution is running, but that it has been accepted by the system to start.
+
+#### **Getting Execution details**
+
+To get detailed information about the execution, the following API can be used.
+
+```bash
+curl --request GET 'http://localhost:4000/api/checks/executions/205e326d-0c25-4f4b-9976-43f9ba1c86d3' \
+--header 'accept: application/json' \
+--header 'Content-Type: application/json' \
+```
+
+> **Note** that calling the execution detail API right after [triggering an execution](#triggering-a-checks-execution) might result in a `404 not found`, because the execution, as mentioned, is _eventually started_.
+> 
+> In this case retry getting the detail of the execution.
+
+Refer to the [API doc](http://localhost:4000/swaggerui) for more information about requests and responses.
+
+### Adding new Checks
+
+Built-in Checks can be found in the Catalog directory at `./priv/catalog/`
+
+In order to implement new checks and test them:
+- write a new [Check Specification](#link-to-specification-doc) file
+- locate the newly created Check in the Catalog directory `./priv/catalog/`
+- test the execution as [previously described](#testing-executions)