diff --git a/README.md b/README.md
index 9a9db6b..bbd0ed8 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,67 @@
 
 [![CI Status](https://github.com/mbarbin/vcs/workflows/ci/badge.svg)](https://github.com/mbarbin/vcs/actions/workflows/ci.yml)
 
-## Code documentation
+A versatile OCaml library for Git interaction
 
-The code documentation of the latest release is built with `odoc` and published
-to `GitHub` pages [here](https://mbarbin.github.io/vcs).
+## Overview
+
+`Vcs` is an OCaml library providing a direct-style API for interacting with Git
+repositories. It's designed as an "interface", or "virtual" library with the
+actual implementation dynamically dispatched at runtime. This design allows for
+high flexibility and adaptability to different use cases.
+
+## Architecture
+
+The `vcs` repository contains several components:
+
+![Git-cli diagram](doc/diagram/gitcli.png)
+
+- **vcs**: The main entry point of the library. Marked with a * to indicate no
+  runtime dependencies.
+- **user-lib**: A placeholder in the diagram for any library that uses `Vcs`.
+  Also marked with a * to indicate no runtime dependencies.
+- **executable**: A placeholder for a runtime component based on `user-lib` that
+  commits to a specific provider and concurrency model.
+- **git-cli**: A IO-free library that parses the output of a `git` cli process.
+- **vcs-git-provider**: An instantiation of `Git_cli` based on an `Eio` runtime.
+- **vcs-git-blocking**: An instantiation of `Git_cli` based on the OCaml `Stdlib`.
+
+![Stdlib diagram](doc/diagram/stdlib.png)
+
+## Design principles
+
+`Vcs` is designed to be backend-agnostic and concurrency-runtime independent.
+It's compatible with both `Eio` and OCaml `Stdlib` runtimes. We plan to explore
+the feasibility of supporting [luv](https://github.com/aantron/luv) and
+[miou](https://github.com/robur-coop/miou) runtimes as separate future work.
+
+The concurrency runtime must be compatible with program written in direct style.
+Runtime based on monadic concurrent models such as `Async` and `Lwt` are
+purposely left outside of the scope of this project.
+
+## How It Works
+
+`Vcs` is an interface composed of [Traits](doc/traits.md), each providing
+different functionalities associated with Git interaction. The dynamic dispatch
+implementation uses the [provider](https://github.com/mbarbin/provider) library.
+
+## Motivation
+
+We aim to create a highly compatible library that can serve various use cases
+and foster community engagement. We also hope to gain practical experience with
+the use of provider-based parametric libraries.
+
+## Relation to ocaml-git
+
+[ocaml-git](https://github.com/mirage/ocaml-git) is a pure OCaml implementation
+of the Git format and protocol. In the `Vcs` framework, an Eio compatible
+`ocaml-git` is a potential `provider` for the interface. We plan to create a
+`Vcs` provider based on `ocaml-git` in the future.
+
+![Ocaml-git diagram](doc/diagram/ocaml-git.png)
+
+## Current Status
+
+The project is currently in the draft stage in a private repository. We're in
+the process of selecting an appropriate license and seeking preliminary
+feedback.
diff --git a/doc/diagram/gitcli.dot b/doc/diagram/gitcli.dot
new file mode 100644
index 0000000..b146638
--- /dev/null
+++ b/doc/diagram/gitcli.dot
@@ -0,0 +1,7 @@
+digraph G {
+    "vcs *" -> "user-lib *";
+    "user-lib *" -> "executable (eio)";
+    "git-cli" -> "vcs-git-provider";
+    eio -> "vcs-git-provider";
+    "vcs-git-provider" -> "executable (eio)";
+}
diff --git a/doc/diagram/gitcli.png b/doc/diagram/gitcli.png
new file mode 100644
index 0000000..2b2b44c
Binary files /dev/null and b/doc/diagram/gitcli.png differ
diff --git a/doc/diagram/ocaml-git.dot b/doc/diagram/ocaml-git.dot
new file mode 100644
index 0000000..36dbbe1
--- /dev/null
+++ b/doc/diagram/ocaml-git.dot
@@ -0,0 +1,7 @@
+digraph G {
+    "vcs *" -> "user-lib *";
+    "user-lib *" -> "executable (eio)";
+    "ocaml-git-eio" -> "ocaml-git-provider";
+    eio -> "ocaml-git-provider";
+    "ocaml-git-provider" -> "executable (eio)";
+}
diff --git a/doc/diagram/ocaml-git.png b/doc/diagram/ocaml-git.png
new file mode 100644
index 0000000..1f761e4
Binary files /dev/null and b/doc/diagram/ocaml-git.png differ
diff --git a/doc/diagram/regen.sh b/doc/diagram/regen.sh
new file mode 100755
index 0000000..27e61e3
--- /dev/null
+++ b/doc/diagram/regen.sh
@@ -0,0 +1,9 @@
+#!/bin/bash -e
+
+# Change the current working directory to the directory where the script is located
+cd "$(dirname "$0")"
+
+for i in `ls *.dot`; do
+    echo "Processing $i ..."
+    dot -Tpng $i -o `echo $i | sed 's/.dot/.png/'`
+done
diff --git a/doc/diagram/stdlib.dot b/doc/diagram/stdlib.dot
new file mode 100644
index 0000000..7694480
--- /dev/null
+++ b/doc/diagram/stdlib.dot
@@ -0,0 +1,7 @@
+digraph G {
+    "vcs *" -> "user-lib *";
+    "user-lib *" -> "executable (blocking)";
+    "git-cli" -> "vcs-git-blocking";
+    stdlib -> "vcs-git-blocking";
+    "vcs-git-blocking" -> "executable (blocking)";
+}
diff --git a/doc/diagram/stdlib.png b/doc/diagram/stdlib.png
new file mode 100644
index 0000000..4c037df
Binary files /dev/null and b/doc/diagram/stdlib.png differ
diff --git a/doc/traits.md b/doc/traits.md
new file mode 100644
index 0000000..b53cd9f
--- /dev/null
+++ b/doc/traits.md
@@ -0,0 +1,33 @@
+# The Power of Traits in `Vcs`
+
+The `Vcs` library leverages the `provider`-based parametric model to offer a
+flexible and adaptable interface for Git interaction. This model, also used in
+the `Eio` library (`Eio.Resource`), allows us to define small scopes of
+functionality, or `Traits`, within the `Vcs` library.
+
+## Experience with `providers`
+
+Our use of the [provider](https://github.com/mbarbin/provider) based parametric
+library in `Vcs` serves as a practical, real-world case study of this pattern.
+
+We aim to bring this pattern to the attention of the community, fostering a
+general understanding that can be applied to other projects using the same
+pattern. In essence, understanding the parametrized model of `Vcs` equates to
+understanding `Eio.Resource`, and vice versa.
+
+## Granularity of the Interface via Trait Granularity
+
+The `Trait` design of `provider` allows us to define specific and isolated
+sub-functionalities within the `Vcs` library. This granularity enables different
+providers to choose which `Trait` they wish to implement, offering a level of
+flexibility not possible with a monolithic functor.
+
+With `Traits`, you can select a provider with the specific set of traits you
+need, without changing any other code. As explained
+[here](https://mbarbin.github.io/provider/provider/Provider/Interface/index.html#type-t),
+provider interfaces come with some notion of phantom types, offering additional
+compiler assistance.
+
+In summary, the use of `Traits` in `Vcs` provides a flexible, adaptable, and
+granular interface for Git interaction, promoting a broader understanding and
+application of the `provider`-based parametric model.
\ No newline at end of file
diff --git a/dune-project b/dune-project
index d00287f..7a507ab 100644
--- a/dune-project
+++ b/dune-project
@@ -15,7 +15,7 @@
 
 (package
  (name vcs)
- (synopsis "A collection of OCaml libraries defining interfaces and providers to interact with git repositories")
+ (synopsis "A versatile OCaml library for Git interaction")
  (depends
   (ocaml
    (>= 5.1))
diff --git a/vcs.opam b/vcs.opam
index f3fddcf..ab052cd 100644
--- a/vcs.opam
+++ b/vcs.opam
@@ -1,7 +1,6 @@
 # This file is generated by dune, edit dune-project instead
 opam-version: "2.0"
-synopsis:
-  "A collection of OCaml libraries defining interfaces and providers to interact with git repositories"
+synopsis: "A versatile OCaml library for Git interaction"
 maintainer: ["Mathieu Barbin"]
 authors: ["Mathieu Barbin"]
 homepage: "https://github.com/mbarbin/vcs"