diff --git a/architecture-docs/.gitignore b/architecture-docs/.gitignore
new file mode 100644
index 0000000..7f123b4
--- /dev/null
+++ b/architecture-docs/.gitignore
@@ -0,0 +1,3 @@
+*.err
+*.odt
+.~lock*
diff --git a/architecture-docs/data-model.md b/architecture-docs/data-model.md
new file mode 100644
index 0000000..9c1abb6
--- /dev/null
+++ b/architecture-docs/data-model.md
@@ -0,0 +1,28 @@
+
+
+# fediversity entity relations
+
+```mermaid
+---
+title: Fediversity entity relations
+---
+erDiagram
+ setup["Fediversity setup"]
+ env["run-time environment"]
+ deployed["deployed configuration"]
+ staged["staged configuration"]
+ token["deployment token"]
+
+ setup }o--o{ env : offers
+ setup ||--o{ operator : serves
+ operator ||--o{ domain : owns
+ deployment }|--|| domain : uses
+ operator ||--o{ deployment : has
+ deployment ||--|{ token : generates
+ deployment ||--o| deployed : has
+ deployment ||--|| staged : has
+ deployed |o--|| staged : compares
+ deployed ||--|{ application : describes
+ application ||--o{ version : follows
+ deployed }|--o{ version : follows
+```
diff --git a/architecture-docs/entity-relations.html b/architecture-docs/entity-relations.html
new file mode 100644
index 0000000..862de45
--- /dev/null
+++ b/architecture-docs/entity-relations.html
@@ -0,0 +1,4 @@
+fediversity entity relations
+![]()
diff --git a/architecture-docs/entity-relations.md b/architecture-docs/entity-relations.md
new file mode 100644
index 0000000..32ccdb2
--- /dev/null
+++ b/architecture-docs/entity-relations.md
@@ -0,0 +1,26 @@
+# fediversity entity relations
+
+```mermaid
+---
+title: Fediversity entity relations
+---
+erDiagram
+ setup["Fediversity setup"]
+ env["run-time environment"]
+ deployed["deployed configuration"]
+ staged["staged configuration"]
+ token["deployment token"]
+
+ setup }o--o{ env : offers
+ setup ||--o{ operator : serves
+ operator ||--o{ domain : owns
+ deployment }|--|| domain : uses
+ operator ||--o{ deployment : has
+ deployment ||--|{ token : generates
+ deployment ||--o| deployed : has
+ deployment ||--|| staged : has
+ deployed |o--|| staged : compares
+ deployed ||--|{ application : describes
+ application ||--o{ version : follows
+ deployed }|--o{ version : follows
+```