diff --git a/README.md b/README.md
index 6113ef48..5c467305 100644
--- a/README.md
+++ b/README.md
@@ -54,15 +54,9 @@ Developing a new Nextcloud client can be as easy as adding some UI and then nece
 
 We have a Matrix space where you can ask questions: https://matrix.to/#/#nextcloud-neon:matrix.org
 
-## Architecture overview
+## Documentation
 
-![Architecture overview diagram](assets/architecture.svg)
-
-The framework consists of multiple packages:
-- For APIs the nextcloud package provides the implementations. The dynamite generator generates the code using the OpenAPI specs.
-- The main package is the neon package that provides widgets and functionality that is useful for building a Nextcloud client. It also manages the global state at runtime so that the app implementations do not have to manage things like multiple accounts for example.
-- The individual apps are implemented as separate packages. Those depend on the neon framework and implement a few interfaces so that the neon framework can use them.
-- On top of all that sits the app package that injects the relevant app implementations into the framework. It is possible to configure which app implementations should be included and how the app is branded.
+See [docs](./docs).
 
 ## Platform support
 
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 00000000..7228791b
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,9 @@
+# Architecture overview
+
+![Architecture overview diagram](architecture.svg)
+
+The framework consists of multiple packages:
+- For APIs the nextcloud package provides the implementations. The dynamite generator generates the code using the OpenAPI specs.
+- The main package is the neon package that provides widgets and functionality that is useful for building a Nextcloud client. It also manages the global state at runtime so that the app implementations do not have to manage things like multiple accounts for example.
+- The individual apps are implemented as separate packages. Those depend on the neon framework and implement a few interfaces so that the neon framework can use them.
+- On top of all that sits the app package that injects the relevant app implementations into the framework. It is possible to configure which app implementations should be included and how the app is branded.
diff --git a/assets/architecture.puml b/docs/architecture.puml
similarity index 100%
rename from assets/architecture.puml
rename to docs/architecture.puml
diff --git a/assets/architecture.svg b/docs/architecture.svg
similarity index 100%
rename from assets/architecture.svg
rename to docs/architecture.svg
diff --git a/tool/generate-assets.sh b/tool/generate-assets.sh
index a0af4822..f82d3ae7 100755
--- a/tool/generate-assets.sh
+++ b/tool/generate-assets.sh
@@ -4,7 +4,5 @@ cd "$(dirname "$0")/.."
 
 color="#f37736"
 
-plantuml -tsvg assets/architecture.puml
-
 wget https://raw.githubusercontent.com/Templarian/MaterialDesign/master/svg/cable-data.svg -O assets/logo.svg
 sed -i "s/<path /<path fill=\"$color\" /g" assets/logo.svg
diff --git a/tool/generate-docs.sh b/tool/generate-docs.sh
new file mode 100755
index 00000000..fb48bde5
--- /dev/null
+++ b/tool/generate-docs.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+set -euxo pipefail
+cd "$(dirname "$0")/.."
+
+plantuml -tsvg docs/*.puml