diff --git a/code/hsec-sync/README.md b/code/hsec-sync/README.md
index 5bb98c2..cefe0b3 100644
--- a/code/hsec-sync/README.md
+++ b/code/hsec-sync/README.md
@@ -5,3 +5,25 @@ Synchronize with the [Haskell advisories database](https://github.com/haskell/se
 ## Building
 
 We aim to support both regular cabal-based and nix-based builds.
+
+## Design
+
+[hsec-tools](../hsec-tools/) is the main entry point for dealing with [security advisories](https://github.com/haskell/security-advisories).
+
+Libraries implementors and services providers will mainly be interested by
+`Security.Advisories.Queries` and `hsec-tools query` which allows querying
+against a directory containing the advisories.
+
+There are two ways for maintaining this local directory up-to-date:
+
+* Manually (based on `git` of fetching archive from GitHub)
+* Relying on `hsec-sync` (either via `Security.Advisories.Sync.sync` or `hsec-sync sync`)
+
+![overview](./overview.png)
+
+The recommended workflow is:
+
+1. Use `hsec-sync` to ensure having an up-to-date advisories directory (created or updated)
+2. Use `hsec-tools` to perform queries against it
+
+![recommended-workflow](./recommended-workflow.png)
diff --git a/code/hsec-sync/hsec-sync.cabal b/code/hsec-sync/hsec-sync.cabal
index e5b4632..4886f61 100644
--- a/code/hsec-sync/hsec-sync.cabal
+++ b/code/hsec-sync/hsec-sync.cabal
@@ -19,7 +19,7 @@ maintainer:      gautier.difolco@gmail.com
 -- A copyright notice.
 -- copyright:
 category:        Data
-extra-doc-files: CHANGELOG.md
+extra-doc-files: CHANGELOG.md, overview.png, recommended-workflow.png
 tested-with:
   GHC ==8.10.7 || ==9.0.2 || ==9.2.8 || ==9.4.8 || ==9.6.3 || ==9.8.1
 
diff --git a/code/hsec-sync/overview.png b/code/hsec-sync/overview.png
new file mode 100644
index 0000000..6011609
Binary files /dev/null and b/code/hsec-sync/overview.png differ
diff --git a/code/hsec-sync/recommended-workflow.png b/code/hsec-sync/recommended-workflow.png
new file mode 100644
index 0000000..6c8ec72
Binary files /dev/null and b/code/hsec-sync/recommended-workflow.png differ