diff --git a/README.md b/README.md
index ed93ac1..d3e3004 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,16 @@
 [Podman Quadlets](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) are awesome, but vastly under-utilized in the Open Source communities.
 This repository gathers all the recipes (hence the name "Cookbook") to deploy Open Source technologies using Podman Quadlets.
 
-## Current cookbooks
+## Architecture guidelines
+
+- SELinux is enabled by default. Privileged containers are avoided whenever possible.
+- Each cookbook runs as a dedicated Linux user, either directly with `--user=` or through user namespaces and UID/GID mapping.
+- Persistent data are stored in `/var/lib/quadlets/$(PROJECT_NAME)`. Precious data are stored in `/var/lib/virtiofs/data/$(PROJECT_NAME)`.
+- Configuration is stored in `/etc/quadlets/$(PROJECT_NAME)`.
+- Each Systemd unit / Podman Quadlet perform only one task. Especially, the one-off initialization procedures, upgrade processes, etc. are run as separate units.
+- Cookbooks are designed to be composable. If you need to deploy a software that needs PostgreSQL as database and a reverse proxy in front, just add the `postgresql` and `traefik` cookbooks as dependencies!
+
+## Available Cookbooks
 
 - [base](base/): base configuration for Fedora CoreOS with fastfetch, tmpfiles setup, and QEMU guest agent.
 - [gitea](gitea/): self-hosted Git service, a lightweight GitHub/GitLab alternative.
@@ -22,6 +31,46 @@ This repository gathers all the recipes (hence the name "Cookbook") to deploy Op
 - [vmagent](vmagent/): Victoria Metrics agent for collecting and forwarding metrics.
 - [vsftpd](vsftpd/): secure FTP server with TLS support and Let's Encrypt certificate integration.
 
+## Cookbook layout
+
+- `Makefile`: Cookbook's Makefile. Includes `../common.mk`. (**REQUIRED**)
+- `overlay.bu`: Fedora CoreOS Butane Specifications to include in the generated Ignition files. (_OPTIONAL_)
+- `fcos.bu`: The Fedora CoreOS Butane Specifications to build the test FCOS Virtual Machine. (_OPTIONAL_)
+- `config/*`: Cookbook's configuration files (read-only). Goes into `/etc/quadlets/$(PROJECT_NAME)`.
+- `config/examples/*`: Cookbook configuration files (sample configuration, to be overwritten for each deployment). Goes into `/etc/quadlets/$(PROJECT_NAME)`.
+- `config/examples/*.env`: Systemd environment files, potentially containing secrets (to be overwritten for each deployment). Goes into `/etc/quadlets/$(PROJECT_NAME)`.
+- `sysctl.d/*.conf`: Sysctl settings. Goes into `/etc/sysctl.d`.
+- `sysctl.d/examples/*.conf`: Sysctl settings (to be overwritten for each deployment). Goes into `/etc/sysctl.d`.
+- `tmpfiles.d/*.conf`: systemd-tmpfiles.d settings. Goes into `/etc/tmpfiles.d`.
+- `tmpfiles.d/examples/*.conf`: systemd-tmpfiles.d settings (to be overwritten for each deployment). Goes into `/etc/tmpfiles.d`.
+- `profile.d/*.conf`: Bash profile settings. Goes into `/etc/profile.d`.
+- `profile.d/examples/*.conf`: Bash profile settings (to be overwritten for each deployment). Goes into `/etc/profile.d`.
+- `other/$(DEPENDENCY)/*`: Sample configuration files to inject into the Cookbook dependencies. For example, `other/postgresql/nextcloud.sql` goes into `/etc/quadlets/postgresql/init.d/nextcloud.sql`. This behavior is described in the `hooks.mk`.
+- `hooks.mk`: the Makefile that registers rules to copy cookbook configuration files when used as a dependency.
+
+## Pre-requisites
+
+- Fedora / CentOS Stream / RHEL or derivative operating system.
+- Systemd
+
+## Development
+
+To develop Podman Quadlets, it is advised to create a Fedora Virtual Machine dedicated to this task.
+
+You can create a Fedora Virtual Machine with the following commands:
+
+```sh
+TODO
+```
+
+Dependencies to install in the VM:
+
+```sh
+dnf install -y make systemd procps-ng @virtualization qemu-img virt-install coreos-installer xterm-resize butane yq podlet
+```
+
+
+
 ## License
 
 MIT