From 1a283f46c802cbbe77ed487eef0ebf7c036c00a9 Mon Sep 17 00:00:00 2001
From: Martin Weise <martin.weise@tuwien.ac.at>
Date: Sun, 19 May 2024 19:51:09 +0200
Subject: [PATCH] WIP doc

---
 .../analysis.md}                              |   0
 .../authentication.md}                        |   0
 .../data.md}                                  |   0
 .../gateway.md}                               |   0
 .../message-broker.md}                        |   0
 .../metadata.md}                              |   0
 .../microservice.md}                          |   0
 .docs/concepts/pid.md                         |   7 ++
 .../relational-database.md}                   |   4 -
 .../search.md}                                |   0
 .../storage.md}                               |   0
 .docs/{system-other-ui.md => concepts/ui.md}  |   0
 .../upload.md}                                |   0
 .docs/{dev-guide-app.md => contributing.md}   |  17 +++-
 .docs/dev-guide-infra.md                      |  78 ------------------
 .docs/dev-overview.md                         |  21 -----
 .docs/help.md                                 |  11 +++
 .docs/index.md                                |  35 +++-----
 .docs/migration.md                            |   6 ++
 .docs/operation-actuator.md                   |   9 --
 .docs/operation-prometheus.md                 |   9 --
 .../extra.scssc                               | Bin 9822 -> 10482 bytes
 .docs/stylesheets/extra.css                   |  17 ++--
 .docs/stylesheets/extra.css.map               |   2 +-
 .docs/stylesheets/extra.scss                  |  15 ++--
 .docs/system-databases-authentication.md      |  33 --------
 .docs/system-databases-metadata.md            |  37 ---------
 .docs/system-databases-search.md              |  45 ----------
 .docs/system-other-search-dashboard.md        |  38 ---------
 .docs/why.md                                  |  16 ++++
 mkdocs.yml                                    |  50 +++++------
 31 files changed, 106 insertions(+), 344 deletions(-)
 rename .docs/{system-services-analyse.md => concepts/analysis.md} (100%)
 rename .docs/{system-services-authentication.md => concepts/authentication.md} (100%)
 rename .docs/{system-services-data.md => concepts/data.md} (100%)
 rename .docs/{system-services-gateway.md => concepts/gateway.md} (100%)
 rename .docs/{system-services-broker.md => concepts/message-broker.md} (100%)
 rename .docs/{system-services-metadata.md => concepts/metadata.md} (100%)
 rename .docs/{system-overview.md => concepts/microservice.md} (100%)
 create mode 100644 .docs/concepts/pid.md
 rename .docs/{system-databases-data.md => concepts/relational-database.md} (99%)
 rename .docs/{system-services-search.md => concepts/search.md} (100%)
 rename .docs/{system-services-storage.md => concepts/storage.md} (100%)
 rename .docs/{system-other-ui.md => concepts/ui.md} (100%)
 rename .docs/{system-services-upload.md => concepts/upload.md} (100%)
 rename .docs/{dev-guide-app.md => contributing.md} (91%)
 delete mode 100644 .docs/dev-guide-infra.md
 delete mode 100644 .docs/dev-overview.md
 create mode 100644 .docs/help.md
 create mode 100644 .docs/migration.md
 delete mode 100644 .docs/operation-actuator.md
 delete mode 100644 .docs/operation-prometheus.md
 delete mode 100644 .docs/system-databases-authentication.md
 delete mode 100644 .docs/system-databases-metadata.md
 delete mode 100644 .docs/system-databases-search.md
 delete mode 100644 .docs/system-other-search-dashboard.md
 create mode 100644 .docs/why.md

diff --git a/.docs/system-services-analyse.md b/.docs/concepts/analysis.md
similarity index 100%
rename from .docs/system-services-analyse.md
rename to .docs/concepts/analysis.md
diff --git a/.docs/system-services-authentication.md b/.docs/concepts/authentication.md
similarity index 100%
rename from .docs/system-services-authentication.md
rename to .docs/concepts/authentication.md
diff --git a/.docs/system-services-data.md b/.docs/concepts/data.md
similarity index 100%
rename from .docs/system-services-data.md
rename to .docs/concepts/data.md
diff --git a/.docs/system-services-gateway.md b/.docs/concepts/gateway.md
similarity index 100%
rename from .docs/system-services-gateway.md
rename to .docs/concepts/gateway.md
diff --git a/.docs/system-services-broker.md b/.docs/concepts/message-broker.md
similarity index 100%
rename from .docs/system-services-broker.md
rename to .docs/concepts/message-broker.md
diff --git a/.docs/system-services-metadata.md b/.docs/concepts/metadata.md
similarity index 100%
rename from .docs/system-services-metadata.md
rename to .docs/concepts/metadata.md
diff --git a/.docs/system-overview.md b/.docs/concepts/microservice.md
similarity index 100%
rename from .docs/system-overview.md
rename to .docs/concepts/microservice.md
diff --git a/.docs/concepts/pid.md b/.docs/concepts/pid.md
new file mode 100644
index 0000000000..c5d769192c
--- /dev/null
+++ b/.docs/concepts/pid.md
@@ -0,0 +1,7 @@
+---
+author: Martin Weise
+---
+
+## tbd
+
+tbd
diff --git a/.docs/system-databases-data.md b/.docs/concepts/relational-database.md
similarity index 99%
rename from .docs/system-databases-data.md
rename to .docs/concepts/relational-database.md
index e290bc1342..468b97ac07 100644
--- a/.docs/system-databases-data.md
+++ b/.docs/concepts/relational-database.md
@@ -2,10 +2,6 @@
 author: Martin Weise
 ---
 
-# Data Database
-
-## tl;dr
-
 !!! debug "Debug Information"
 
     Image: [`bitnami/mariadb-galera:11.2.2-debian-11-r0`](https://hub.docker.com/r/bitnami/mariadb-galera)
diff --git a/.docs/system-services-search.md b/.docs/concepts/search.md
similarity index 100%
rename from .docs/system-services-search.md
rename to .docs/concepts/search.md
diff --git a/.docs/system-services-storage.md b/.docs/concepts/storage.md
similarity index 100%
rename from .docs/system-services-storage.md
rename to .docs/concepts/storage.md
diff --git a/.docs/system-other-ui.md b/.docs/concepts/ui.md
similarity index 100%
rename from .docs/system-other-ui.md
rename to .docs/concepts/ui.md
diff --git a/.docs/system-services-upload.md b/.docs/concepts/upload.md
similarity index 100%
rename from .docs/system-services-upload.md
rename to .docs/concepts/upload.md
diff --git a/.docs/dev-guide-app.md b/.docs/contributing.md
similarity index 91%
rename from .docs/dev-guide-app.md
rename to .docs/contributing.md
index 6d20ae5065..4268b7807f 100644
--- a/.docs/dev-guide-app.md
+++ b/.docs/contributing.md
@@ -1,4 +1,10 @@
-# Application Developer Guide
+---
+author: Martin Weise
+---
+
+## Contributing
+
+We welcome contributions to DBRepo!
 
 ## Dependencies
 
@@ -104,4 +110,11 @@ repository.
 
 ## Documentation
 
-For consistency reasons across the documentation, the resolution needs to be 1280x800 (16:10 ratio)
\ No newline at end of file
+For consistency reasons across the documentation, the resolution needs to be 1280x800 (16:10 ratio)
+
+## Roadmap
+
+- [x] Q1: Python library, versioning in every component, bumping frontend versions, i18n
+- [ ] Q2: Kubernetes deployment guidelines for OpenShift
+- [ ] Q3: Frontend tests, database dashboards
+- [ ] Q4: Release of 2.0.0
diff --git a/.docs/dev-guide-infra.md b/.docs/dev-guide-infra.md
deleted file mode 100644
index cb01a76473..0000000000
--- a/.docs/dev-guide-infra.md
+++ /dev/null
@@ -1,78 +0,0 @@
-# Infrastructure Developer Guide
-
-## tl;dr
-
-```shell
-make cluster-start cluster-image-pull cluster-install
-```
-
-## Dependencies
-
-Local development depends on the following packages for Debian 12:
-
-```shell
-apt install -y make
-```
-
-Required tools with their own installing guides:
-
-* [Docker Engine](https://docs.docker.com/engine/install/) 24+
-* [Minikube](https://minikube.sigs.k8s.io/docs/start/) 1.32.0
-
-## Getting Started
-
-Start the local development cluster with the Docker driver (takes at least 8 vCPUs and 12GB RAM). It installs a Minikube
-single-node Kubernetes cluster with enabled Ingress and Dashboard
-
-```shell
-make cluster-start
-```
-
-Build the local images with `make build-docker` and copy them to the cluster image cache:
-
-```shell
-make cluster-image-pull
-```
-
-Build and install the Helm chart:
-
-```shell
-make cluster-install
-```
-
-## Debug
-
-Open the Minikube (Kubernetes) Dashboard:
-
-```shell
-make cluster-dashboard
-```
-
-<figure markdown>
-![Minikube Dashboard](images/screenshots/minikube-dashboard.png)
-<figcaption>Figure 1: Minikube Dashboard</figcaption>
-</figure>
-
-Optionally enable the Prometheus metrics addon with:
-
-```shell
-minikube addons enable metrics-server
-```
-
-## Test
-
-Test if the Helm chart raises errors on start (the script aborts after 5 minutes automatically if some pods are not
-starting or erroneous).
-
-```shell
-make cluster-test
-```
-
-## Uninstall
-
-To uninstall DBRepo from the local Minikube cluster, removing all data:
-
-```shell
-make cluster-uninstall
-```
-
diff --git a/.docs/dev-overview.md b/.docs/dev-overview.md
deleted file mode 100644
index e7c0e808b9..0000000000
--- a/.docs/dev-overview.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Overview
-
-## Guides
-
-* The [application developer guide](../dev-guide-app) guides you through the steps on how to build DBRepo from
-  scratch and customize the application.
-* The [infrastructure developer guide](../dev-guide-infra) guides you through the steps on how to build and customize
-  the operation environment.
-
-## Organization
-
-* Monthly sprints with patch-releases (i.e. `1.4.2` in February, `1.4.3` in March, ...).
-* Branching from `dev` for feature development, one release branch per patch (i.e. `release-1.4.2` for release version
-  `1.4.2`).
-
-## Roadmap
-
-- [x] Q1: Python library, versioning in every component, bumping frontend versions, i18n
-- [ ] Q2: Kubernetes deployment guidelines for OpenShift
-- [ ] Q3: Frontend tests, database dashboards
-- [ ] Q4: Release of 2.0.0
\ No newline at end of file
diff --git a/.docs/help.md b/.docs/help.md
new file mode 100644
index 0000000000..5dd7d1c58a
--- /dev/null
+++ b/.docs/help.md
@@ -0,0 +1,11 @@
+---
+author: Martin Weise
+---
+
+## Usage Documentation
+
+The [usage documentation](#) is the most complete guide on how to use DBRepo.
+
+## API Documentation
+
+The [API documentation](#) present reference docs for all APIs.
diff --git a/.docs/index.md b/.docs/index.md
index 4eb23f9e8a..882dff6841 100644
--- a/.docs/index.md
+++ b/.docs/index.md
@@ -1,24 +1,13 @@
 ---
 author: Martin Weise
-hide:
-- navigation
-social:
-  cards_layout_options:
-    title: Documentation that simply works
 ---
 
-## Problem Statement
+[![CI/CD Pipeline](https://gitlab.phaidra.org/fair-data-austria-db-repository/fda-services/badges/master/pipeline.svg)](https://gitlab.phaidra.org/fair-data-austria-db-repository/fda-services){ tabindex=-1 }
+[![Code Coverage](https://gitlab.phaidra.org/fair-data-austria-db-repository/fda-services/badges/master/coverage.svg)](https://gitlab.phaidra.org/fair-data-austria-db-repository/fda-services){ tabindex=-1 }
+[![GitLab Release](https://img.shields.io/gitlab/v/release/fair-data-austria-db-repository%2Ffda-services?gitlab_url=https%3A%2F%2Fgitlab.phaidra.org&display_name=release&style=flat)](https://gitlab.phaidra.org/fair-data-austria-db-repository/fda-services){ tabindex=-1 }
+[![GitLab License](https://img.shields.io/gitlab/license/fair-data-austria-db-repository%2Ffda-services?gitlab_url=https%3A%2F%2Fgitlab.phaidra.org%2F&style=flat)](https://gitlab.phaidra.org/fair-data-austria-db-repository/fda-services){ tabindex=-1 }
+[![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/dbrepo)](https://artifacthub.io/packages/helm/dbrepo/dbrepo){ tabindex=-1 }
 
-Digital repositories see themselves more frequently encountered with the problem of making databases accessible in their
-collection. Challenges revolve around organizing, searching and retrieving content stored within databases and
-constitute a major technical burden as their internal representation greatly differs from static documents most digital
-repositories are designed for.
-
-## Application Areas
-
-We present a database repository system that allows researchers to ingest data into a central, versioned repository
-through common interfaces, provides efficient access to arbitrary subsets of data even when the underlying data store is
-evolving, allows reproducing of query results and supports findable-, accessible-, interoperable- and reusable data.
 
 ## Features
 
@@ -44,12 +33,14 @@ edge devices like sensors and store them asynchronous in DBRepo. [Learn more.](.
 ### Cloud Native
 
 Our lightweight Helm chart allows for installations on any cloud provider or private-cloud setting that has an
-underlying PV storage provider. DBRepo can be installed from the Artifacthub repository. Databases are managed as 
-MariaDB Galera Cluster with high degree of availability ensuring your data is always accessible.
+underlying PV storage provider. DBRepo can be installed from 
+the [Artifact Hub](https://artifacthub.io/packages/helm/dbrepo/dbrepo) repository. Databases are managed as MariaDB
+Galera Cluster with high degree of availability ensuring your data is always accessible.
 [Learn more.](../deployment-helm/)
 
-## More Information
+## Demo Site
+
+We run a small demonstration instance so you can see the latest version of DBRepo in action. The demonstration instance
+is updated with new releases and should be considered ephemeral.
 
-- Demonstration instance [https://dbrepo1.ec.tuwien.ac.at](https://dbrepo1.ec.tuwien.ac.at)
-- Test instance [https://test.dbrepo.tuwien.ac.at](https://test.dbrepo.tuwien.ac.at)
-- System description [https://doi.org/10.2218/ijdc.v17i1.825](https://doi.org/10.2218/ijdc.v17i1.825)
+[:fontawesome-solid-flask: Demonstration Instance](https://test.dbrepo.tuwien.ac.at){ .md-button .md-button--primary }
\ No newline at end of file
diff --git a/.docs/migration.md b/.docs/migration.md
new file mode 100644
index 0000000000..fe8052fc8f
--- /dev/null
+++ b/.docs/migration.md
@@ -0,0 +1,6 @@
+---
+author: Martin Weise
+---
+
+## Migration Guide
+
diff --git a/.docs/operation-actuator.md b/.docs/operation-actuator.md
deleted file mode 100644
index 581027daf1..0000000000
--- a/.docs/operation-actuator.md
+++ /dev/null
@@ -1,9 +0,0 @@
----
-author: Martin Weise
----
-
-# Actuators
-
-## Usage
-
-TBD documentation of all Healthiness endpoints
\ No newline at end of file
diff --git a/.docs/operation-prometheus.md b/.docs/operation-prometheus.md
deleted file mode 100644
index 8c31d0e94e..0000000000
--- a/.docs/operation-prometheus.md
+++ /dev/null
@@ -1,9 +0,0 @@
----
-author: Martin Weise
----
-
-# Prometheus
-
-## Usage
-
-TBD documentation of all prometheus metrics
diff --git a/.docs/stylesheets/.sass-cache/10990fa183107f4149f38216a4d00fe324a8131e/extra.scssc b/.docs/stylesheets/.sass-cache/10990fa183107f4149f38216a4d00fe324a8131e/extra.scssc
index af6f91ae62d67828dfbb9235363407bea6d6dd0a..381e95eee429698ebbbc5f4a1b6337eb2823178d 100644
GIT binary patch
literal 10482
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

delta 3316
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
a9j&=0uUE5~{83Gh(R#Ct`V~edlMn!0i}cd~

diff --git a/.docs/stylesheets/extra.css b/.docs/stylesheets/extra.css
index fbdf67bf13..5356c0f2fe 100644
--- a/.docs/stylesheets/extra.css
+++ b/.docs/stylesheets/extra.css
@@ -1,17 +1,20 @@
 :root,
 [data-md-color-accent=indigo] {
   --md-primary-fg-color: #006699;
-  --md-accent-fg-color: #005c8a /* darken 10% */ ;
-  --md-primary-fg-color--dark: #00537c /* darken 10% */ ; }
+  --md-accent-fg-color: #005c8a;
+  /* darken 10% */
+  --md-primary-fg-color--dark: #00537c;
+  /* darken 10% */ }
 
 img.img-border {
   border: 1px solid #b3b3b3; }
 
-.md-typeset .md-button.md-button--secondary {
-  background: #ffffff; }
-  .md-typeset .md-button.md-button--secondary:focus, .md-typeset .md-button.md-button--secondary:hover {
-    color: var(--md-primary-fg-color);
-    background: #e5e5e5; }
+.md-typeset .md-button.md-button--primary {
+  color: white !important; }
+
+.md-typeset .md-button.md-button--secondary:focus, .md-typeset .md-button.md-button--secondary:hover {
+  color: var(--md-primary-fg-color--dark);
+  background: #e5e5e5; }
 
 .md-main .md-content a:not(.action-button):not([tabindex]),
 .md-main .md-content a:not(.action-button):not([tabindex]) {
diff --git a/.docs/stylesheets/extra.css.map b/.docs/stylesheets/extra.css.map
index d6ff724b3c..5c5c3a911f 100644
--- a/.docs/stylesheets/extra.css.map
+++ b/.docs/stylesheets/extra.css.map
@@ -1,6 +1,6 @@
 {
 "version": 3,
-"mappings": "AAAA;6BAC8B;EAC5B,qBAAqB,CAAC,QAAQ;EAC9B,oBAAoB,CAAC,0BACvB;EACE,2BAA2B,CAAC,0BAC9B;;AAGA,cAAe;EACb,MAAM,EAAE,iBAAiB;;AAG3B,2CAA4C;EAC1C,UAAU,EAAE,OAAO;EAEnB,oGACQ;IACN,KAAK,EAAE,0BAA0B;IACjC,UAAU,EAAE,OAAO;;AAKvB;0DAC2D;EACzD,KAAK,EAAE,uBAAuB;EAC9B,aAAa,EAAE,oCAAoC;EAEnD;;kEACQ;IACN,KAAK,EAAE,uBAAuB;IAC9B,aAAa,EAAE,0CAA0C;;AAK7D,UAAW;EACT,gBAAgB,EAAE,gCAAgC",
+"mappings": "AAAA;6BAC8B;EAC5B,qBAAqB,CAAC,QAAQ;EAC9B,oBAAoB,CAAC,QAAQ;EAAE,gBAAgB;EAC/C,2BAA2B,CAAC,QAAQ;EAAE,gBAAgB;;AAGxD,cAAe;EACb,MAAM,EAAE,iBAAiB;;AAG3B,yCAA0C;EACxC,KAAK,EAAE,gBAAgB;;AAIvB,oGACQ;EACN,KAAK,EAAE,gCAAgC;EACvC,UAAU,EAAE,OAAO;;AAIvB;0DAC2D;EACzD,KAAK,EAAE,uBAAuB;EAC9B,aAAa,EAAE,oCAAoC;EAEnD;;kEACQ;IACN,KAAK,EAAE,uBAAuB;IAC9B,aAAa,EAAE,0CAA0C;;AAK7D,UAAW;EACT,gBAAgB,EAAE,gCAAgC",
 "sources": ["extra.scss"],
 "names": [],
 "file": "extra.css"
diff --git a/.docs/stylesheets/extra.scss b/.docs/stylesheets/extra.scss
index 59fee68b6e..a595e585b4 100644
--- a/.docs/stylesheets/extra.scss
+++ b/.docs/stylesheets/extra.scss
@@ -1,24 +1,23 @@
 :root,
 [data-md-color-accent=indigo] {
   --md-primary-fg-color: #006699;
-  --md-accent-fg-color: #005c8a /* darken 10% */
-;
-  --md-primary-fg-color--dark: #00537c /* darken 10% */
-;
+  --md-accent-fg-color: #005c8a; /* darken 10% */
+  --md-primary-fg-color--dark: #00537c; /* darken 10% */
 }
 
 img.img-border {
   border: 1px solid #b3b3b3;
 }
 
-.md-typeset .md-button.md-button--secondary {
-  background: #ffffff;
+.md-typeset .md-button.md-button--primary {
+  color: white !important;
+}
 
+.md-typeset .md-button.md-button--secondary {
   &:focus,
   &:hover {
-    color: var(--md-primary-fg-color);
+    color: var(--md-primary-fg-color--dark);
     background: #e5e5e5 /* darken 10% */
-  ;
   }
 }
 
diff --git a/.docs/system-databases-authentication.md b/.docs/system-databases-authentication.md
deleted file mode 100644
index 42b729403f..0000000000
--- a/.docs/system-databases-authentication.md
+++ /dev/null
@@ -1,33 +0,0 @@
----
-author: Martin Weise
----
-
-# Authentication Database
-
-## tl;dr
-
-!!! debug "Debug Information"
-
-    Image: [`bitnami/mariadb:11.2.2-debian-11-r0`](https://hub.docker.com/r/bitnami/mariadb)
-
-    * Ports: 3306/tcp
-    * JDBC: `jdbc://mariadb:<hostname>:3306`
-
-## Overview
-
-This is the database in which the [Authentication Service](../system-services-authentication) writes into. In the
-default configuration, only MariaDB is supported.
-
-## Limitations
-
-* No support for MariaDB Galera at the moment.
-
-!!! question "Do you miss functionality? Do these limitations affect you?"
-
-    We strongly encourage you to help us implement it as we are welcoming contributors to open-source software and get
-    in [contact](../contact) with us, we happily answer requests for collaboration with attached CV and your programming 
-    experience!
-
-## Security
-
-(none)
diff --git a/.docs/system-databases-metadata.md b/.docs/system-databases-metadata.md
deleted file mode 100644
index 4ff9980f25..0000000000
--- a/.docs/system-databases-metadata.md
+++ /dev/null
@@ -1,37 +0,0 @@
----
-author: Martin Weise
----
-
-# Metadata Database
-
-## tl;dr
-
-!!! debug "Debug Information"
-
-    Image: [`dbrepo/metadata-db:__APPVERSION__`](https://hub.docker.com/r/dbrepo/metadata-db)
-
-    * Ports: 3306/tcp
-    * JDBC: `jdbc://mariadb:<hostname>:3306`
-
-It is the core component of the project. It is a relational database that contains metadata about all researcher
-database created in the database repository like column names, check expressions, value enumerations or key/value
-constraints and relevant data for citing data sets. Additionally, the concept, e.g. URI of units of measurements of
-numerical columns is stored in the Metadata Database in order to provide semantic knowledge context. We use MariaDB for
-its rich capabilities in the reference implementation.
-
-The default credentials are `root:dbrepo` for the database `fda`. Connect to the database via the JDBC connector on
-port `3306`.
-
-## Limitations
-
-(none)
-
-!!! question "Do you miss functionality? Do these limitations affect you?"
-
-    We strongly encourage you to help us implement it as we are welcoming contributors to open-source software and get
-    in [contact](../contact) with us, we happily answer requests for collaboration with attached CV and your programming 
-    experience!
-
-## Security
-
-(none)
diff --git a/.docs/system-databases-search.md b/.docs/system-databases-search.md
deleted file mode 100644
index 130347215b..0000000000
--- a/.docs/system-databases-search.md
+++ /dev/null
@@ -1,45 +0,0 @@
----
-author: Martin Weise
----
-
-# Search Database
-
-## tl;dr
-
-!!! debug "Debug Information"
-
-    Image: [`dbrepo/search-db:__APPVERSION__`](https://hub.docker.com/r/dbrepo/search-db)
-
-    * Ports: 9200/tcp
-
-## Overview
-
-It processes search requests from the Gateway Service for full-text lookups in 
-the [Metadata Database](../system-databases-metadata). We use [OpenSearch](https://opensearch.org/) in the default 
-configuration and create a searchable index on all databases that is updated regularly by 
-the [Mirror Service](../system-services-mirror).
-
-All requests need to be authenticated, by default the credentials `admin:admin` are used.
-
-Please see the [Search Database Dashboard](../system-other-search-dashboard) for information how to inspect the Search
-Database more efficient.
-
-## Limitations
-
-(none)
-
-!!! question "Do you miss functionality? Do these limitations affect you?"
-
-    We strongly encourage you to help us implement it as we are welcoming contributors to open-source software and get
-    in [contact](../contact) with us, we happily answer requests for collaboration with attached CV and your programming 
-    experience!
-
-## Security
-
-1. Change the default credentials in the [Search Database Dashboard](../system-other-search-dashboard) with the default
-   credentials `admin:admin` and navigate to your username on the top right and click "Reset password".
-
-<figure markdown>
-   ![Data ingest](images/opensearch-dashboards-reset-pw.png){ .img-border }
-   <figcaption>Reset the admin password in Opensearch Dashboards</figcaption>
-</figure>
diff --git a/.docs/system-other-search-dashboard.md b/.docs/system-other-search-dashboard.md
deleted file mode 100644
index dd23d56c67..0000000000
--- a/.docs/system-other-search-dashboard.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-author: Martin Weise
----
-
-# Search Database Dashboard
-
-## tl;dr
-
-!!! debug "Debug Information"
-
-    Image: [`opensearchproject/opensearch-dashboards:2.10.0`](https://hub.docker.com/r/opensearchproject/opensearch-dashboards)
-
-    * Ports: 5601/tcp
-    * UI: `http://<hostname>/admin/dashboard/`
-
-## Overview
-
-It provides a *graphical user interface* (GUI) for an administrator to interact with 
-the [Search Database](../system-databases-search).
-
-<figure markdown>
-   ![Data ingest](images/opensearch-dashboards.png){ .img-border }
-   <figcaption>Opensearch Dashboards on first start</figcaption>
-</figure>
-
-## Limitations
-
-(none)
-
-!!! question "Do you miss functionality? Do these limitations affect you?"
-
-    We strongly encourage you to help us implement it as we are welcoming contributors to open-source software and get
-    in [contact](../contact) with us, we happily answer requests for collaboration with attached CV and your programming 
-    experience!
-
-## Security
-
-(none)
diff --git a/.docs/why.md b/.docs/why.md
new file mode 100644
index 0000000000..71175d013b
--- /dev/null
+++ b/.docs/why.md
@@ -0,0 +1,16 @@
+---
+author: Martin Weise
+---
+
+## Why use DBRepo?
+
+Digital repositories see themselves more frequently encountered with the problem of making databases accessible in their
+collection. Challenges revolve around organizing, searching and retrieving content stored within databases and
+constitute a major technical burden as their internal representation greatly differs from static documents most digital
+repositories are designed for.
+
+## Application Areas
+
+We present a database repository system that allows researchers to ingest data into a central, versioned repository
+through common interfaces, provides efficient access to arbitrary subsets of data even when the underlying data store is
+evolving, allows reproducing of query results and supports findable-, accessible-, interoperable- and reusable data.
diff --git a/mkdocs.yml b/mkdocs.yml
index 05933f2ddd..d4969e8840 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -5,33 +5,27 @@ site_author: Research Unit Data Science, Technische Universit&auml;t Wien
 copyright: CC-BY 4.0 Technische Universit&auml;t Wien & Universit&auml;t Wien
 docs_dir: .docs
 nav:
-  - Home: index.md
-  - Deployment:
-    - Docker Compose: deployment-docker-compose.md
+  - Get Started:
+    - Welcome to DBRepo: index.md
+    - Why use DBRepo: why.md
+    - Help with DBRepo: help.md
+    - Installation: deployment-docker-compose.md
     - Kubernetes: deployment-helm.md
-  - System:
-    - Overview: system-overview.md
-    - Services:
-      - Analyse Service: system-services-analyse.md
-      - Authentication Service: system-services-authentication.md
-      - Broker Service: system-services-broker.md
-      - Data Service: system-services-data.md
-      - Gateway Service: system-services-gateway.md
-      - Metadata Service: system-services-metadata.md
-      - Search Service: system-services-search.md
-      - Storage Service: system-services-storage.md
-      - Upload Service: system-services-upload.md
-    - Databases:
-      - Authentication Database: system-databases-authentication.md
-      - Data Database: system-databases-data.md
-      - Metadata Database: system-databases-metadata.md
-      - Search Database: system-databases-search.md
-    - Other:
-      - User Interface: system-other-ui.md
-      - Search Database Dashboard: system-other-search-dashboard.md
-    - Operation:
-      - Actuator: operation-actuator.md
-      - Prometheus: operation-prometheus.md
+    - Migration Guide: migration.md
+    - contributing.md
+  - Concepts:
+    - Microservice: concepts/microservice.md
+    - Persistent Identifier: concepts/pid.md
+    - (Meta-)Data: concepts/data.md
+    - Analysis: concepts/analysis.md
+    - Authentication: concepts/authentication.md
+    - Message Broker: concepts/message-broker.md
+    - Gateway: concepts/gateway.md
+    - Search: concepts/search.md
+    - Storage: concepts/storage.md
+    - Upload: concepts/upload.md
+    - Relational Database: concepts/relational-database.md
+    - User Interface: concepts/ui.md
   - Usage:
     - Overview: usage-overview.md
     - Python Library: usage-python.md
@@ -39,10 +33,6 @@ nav:
       - Authentication Service: usage-authentication.md
       - Storage Service: usage-storage.md
       - Upload Service: usage-upload.md
-  - Development:
-    - Overview: dev-overview.md
-    - Application Guide: dev-guide-app.md
-    - Infrastructure Guide: dev-guide-infra.md
   - publications.md
   - contact.md
 extra_css:
-- 
GitLab