diff --git a/README.md b/README.md
deleted file mode 100644
--- a/README.md
+++ /dev/null
@@ -1,9 +0,0 @@
-swh-vault
-=========
-
-User-facing service that allows to retrieve parts of the archive as
-self-contained bundles.
-
-See the
-[documentation](https://docs.softwareheritage.org/devel/swh-vault/index.html)
-for more details.
diff --git a/README.rst b/README.rst
new file mode 120000
--- /dev/null
+++ b/README.rst
@@ -0,0 +1 @@
+docs/README.rst
\ No newline at end of file
diff --git a/docs/README.rst b/docs/README.rst
new file mode 100644
--- /dev/null
+++ b/docs/README.rst
@@ -0,0 +1,45 @@
+Software Heritage - Vault
+=========================
+
+User-facing service that allows to retrieve parts of the archive as
+self-contained bundles (e.g., individual releases, entire repository snapshots,
+etc.)
+The creation of a bundle is called "cooking" a bundle.
+
+
+Architecture
+------------
+
+The vault is made of two main parts:
+
+1. a stateful RPC server called the **backend**
+2. Celery tasks, called **cookers**
+
+The Vault backend
+~~~~~~~~~~~~~~~~~
+
+The Vault backend is the RPC server other |swh| components (mainly
+:ref:`swh-web <swh-web>`) interact with.
+
+It is in charge of receiving cooking requests, scheduling corresponding tasks (via
+:ref:`swh-scheduler <swh-scheduler>` and Celery), getting heartbeats and final
+results from these, cooking tasks, and finally serving the results.
+
+It uses the same RPC protocol as the other component of the archive, and
+its interface is described in :mod:`swh.vault.interface`.
+
+The cookers
+~~~~~~~~~~~
+
+Cookers are Python modules/classes, each in charge of cooking a type of bundle.
+The main ones are :mod:`swh.vault.cookers.directory` for flat tarballs of directories,
+and :mod:`swh.vault.cookers.git_bare` for bare ``.git`` repositories of any
+type of git object.
+They all derive from :class:`swh.vault.cookers.base.BaseVaultCooker`.
+
+The base cooker first notifies the backend the cooking task is in progress,
+then runs the cooker (which does the bundle-specific handling and uploads the result),
+then notifies the backend of the final result (success/failure).
+
+Cookers may notify the backend of the progress, so they can be displayed in
+swh-web's vault interface, which polls the status from the vault backend.
diff --git a/docs/index.rst b/docs/index.rst
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,11 +1,6 @@
 .. _swh-vault:
 
-Software Heritage - Vault
-=========================
-
-User-facing service that allows to retrieve parts of the archive as
-self-contained bundles (e.g., individual releases, entire repository snapshots,
-etc.)
+.. include:: README.rst
 
 
 .. toctree::
diff --git a/setup.py b/setup.py
--- a/setup.py
+++ b/setup.py
@@ -12,7 +12,7 @@
 here = path.abspath(path.dirname(__file__))
 
 # Get the long description from the README file
-with open(path.join(here, "README.md"), encoding="utf-8") as f:
+with open(path.join(here, "README.rst"), encoding="utf-8") as f:
     long_description = f.read()
 
 
@@ -39,7 +39,7 @@
     name="swh.vault",
     description="Software Heritage vault",
     long_description=long_description,
-    long_description_content_type="text/markdown",
+    long_description_content_type="text/x-rst",
     python_requires=">=3.7",
     author="Software Heritage developers",
     author_email="swh-devel@inria.fr",