diff --git a/README.md b/README.md
index 10b27944..27e455a4 100644
--- a/README.md
+++ b/README.md
@@ -1,69 +1,49 @@
+# Brass
+A webservice to plan and organize personnel deployment for [Brandsicherheitswachen](https://de.wikipedia.org/wiki/Brandsicherheitswache) (german; fire watch).
+
+# Key Technologies
+- [actix-web](https://actix.rs/)
+- [sqlx](https://github.com/launchbadge/sqlx)
+- [askama](https://github.com/askama-rs/askama)
+- [lettre](https://lettre.rs/)
+- [htmx](https://htmx.org/)
+- [hyperscript](https://hyperscript.org/)
+- [bulma](https://bulma.io/)
+- great inspiration for project structure and tooling: [gerust.rs](https://gerust.rs)
+
 # Getting started with developing
 1. Clone the repository.
 2. Install and configure Postgresql. Create a new database for brass: `createdb brass`.
-3. TODO: Configure DB name, DB user & pass, DB connection string, ...
-4. Install sqlx-cli: `cargo install sqlx-cli`
-5. Migrate the database: `sqlx database setup`
-6. Create superuse: `cargo r -- createadmin`
+3. Configure database connection string in `.env` config file.
+4. Install required development tools `cargo install <tool>`
+    - sqlx-cli
+    - mailtutan
+    - cargo-watch
+    - cargo-nextest
+6. Migrate the development and test database: `cargo db migrate -e development` & `cargo db migrate -e test`
+7. Create superuser: `cargo r -- createadmin`
+8. Run and recompile application on file change: `cargo w`
+9. Run tests via nextest and review possible snapshot changes: `cargo t`
 
-## Useful stuff
-- cargo-watch, cargo-add
-- mailtutan
+# Build & Deploy
+1. Clone the repository.
+2. Build release `cargo b --release`.
+3. Copy the artifact `target/release/brass-web` to the desired location. Make it executable `chmod +x brass-web`.
+4. Create Postgresql database on the target host, configure your mail server.
+5. Configuration for Brass is done via Environment Variables, see `.env` for a list.
+6. Migrate the database `[LIST_OF_ENV_VARIABLES] brass-web migrate`.
+7. Create a superuser `[LIST_OF_ENV_VARIABLES] brass-web createadmin`.
+8. Create some sort of service file (systemd .service, openbsd rc.conf, ...) to run Brass in the background. Examples can be found in `docs/` directory.
 
+# Contributing & Issues
+Code lies on my private gitea instance, thus there's no easy way for creating issues or making contributions. If you've got an issue or want to contribute, write me an email and we'll figure it out.
 
-## Example Deployment OpenBSD
-```
-#!/bin/ksh
+# Project Structure
+- TODO
 
-DATABASE_URL=postgresql://brass:pw@localhost/brass
-SECRET_KEY=""
-HOSTNAME="brass.tfld.de"
-SERVER_ADDRESS="127.0.0.1"
-SERVER_PORT="8081"
-SMTP_SERVER="localhost"
-SMTP_PORT="25"
-SMTP_TLSTYPE="none"
-ENVLIST="DATABASE_URL=$DATABASE_URL SECRET_KEY=$SECRET_KEY HOSTNAME=$HOSTNAME SERVER_ADDRESS=$SERVER_ADDRESS SERVER_PORT=$SERVER_PORT SMTP_SERVER=$SMTP_SERVER SMTP_PORT=$SMTP_PORT SMTP_TLSTYPE=$SMTP_TLSTYPE"
-RUST_LOG="info,actix_server=error"
+# Further Reading
+More in depth documentation about design decisions, helpful commands and database schema can be found in `docs/` directory.
 
-ENVLIST="DATABASE_URL=$DATABASE_URL SECRET_KEY=$SECRET_KEY HOSTNAME=$HOSTNAME SERVER_ADDRESS=$SERVER_ADDRESS SERVER_PORT=$SERVER_PORT SMTP_SERVER=$SMTP_SERVER SMTP_LOGIN=$SMTP_LOGIN SMTP_PASSWORD=$SMTP_PASSWORD SMTP_PORT=$SMTP_PORT SMTP_TLSTYPE=$SMTP_TLSTYPE RUST_LOG=$RUST_LOG"
-
-daemon="$ENVLIST /usr/local/bin/brass"
-daemon_user="www"
-daemon_logger="daemon.info"
-
-. /etc/rc.d/rc.subr
-
-pexp=".*/usr/local/bin/brass.*"
-
-rc_bg=YES
-
-rc_cmd $1
-```
-
-
-```ini
-# Postgres
-# DATABASE_URL=postgres://postgres@localhost/my_database
-# SQLite
-DATABASE_URL=postgresql://brass:password@localhost/brass
-# 64 byte long
-SECRET_KEY="secret key"
-HOSTNAME="brass.tfld.de"
-ADDRESS="127.0.0.1"
-PORT="8081"
-
-SMTP_SERVER="localhost"
-SMTP_PORT="25"
-# SMTP_LOGIN=""
-# SMTP_PASSWORD=""
-SMTP_TLSTYPE="none"
-```
-
-## drop test databases
-```bash
-for dbname in $(psql -c "copy (select datname from pg_database where datname like 'brass_test_%') to stdout") ; do
-    echo "$dbname"
-    #dropdb -i "$dbname"
-done
-```
+# Copyright & License
+Copyright 2025 Max Hohlfeld
+Brass is licensed under [GNU AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html#license-text).
diff --git a/doc/drop_test_databases.md b/doc/drop_test_databases.md
new file mode 100644
index 00000000..f14f7d5a
--- /dev/null
+++ b/doc/drop_test_databases.md
@@ -0,0 +1,8 @@
+# Drop all test databases
+
+```bash
+for dbname in $(psql -c "copy (select datname from pg_database where datname like 'brass_test_%') to stdout") ; do
+    echo "$dbname"
+    #dropdb -i "$dbname"
+done
+```
diff --git a/doc/example_deployment_openbsd.md b/doc/example_deployment_openbsd.md
new file mode 100644
index 00000000..0741045f
--- /dev/null
+++ b/doc/example_deployment_openbsd.md
@@ -0,0 +1,31 @@
+# Example Deployment OpenBSD
+- list of env variables may not be up to date
+
+```sh
+#!/bin/ksh
+
+DATABASE_URL=postgresql://brass:pw@localhost/brass
+SECRET_KEY=""
+HOSTNAME="brass.tfld.de"
+SERVER_ADDRESS="127.0.0.1"
+SERVER_PORT="8081"
+SMTP_SERVER="localhost"
+SMTP_PORT="25"
+SMTP_TLSTYPE="none"
+ENVLIST="DATABASE_URL=$DATABASE_URL SECRET_KEY=$SECRET_KEY HOSTNAME=$HOSTNAME SERVER_ADDRESS=$SERVER_ADDRESS SERVER_PORT=$SERVER_PORT SMTP_SERVER=$SMTP_SERVER SMTP_PORT=$SMTP_PORT SMTP_TLSTYPE=$SMTP_TLSTYPE"
+RUST_LOG="info,actix_server=error"
+
+ENVLIST="DATABASE_URL=$DATABASE_URL SECRET_KEY=$SECRET_KEY HOSTNAME=$HOSTNAME SERVER_ADDRESS=$SERVER_ADDRESS SERVER_PORT=$SERVER_PORT SMTP_SERVER=$SMTP_SERVER SMTP_LOGIN=$SMTP_LOGIN SMTP_PASSWORD=$SMTP_PASSWORD SMTP_PORT=$SMTP_PORT SMTP_TLSTYPE=$SMTP_TLSTYPE RUST_LOG=$RUST_LOG"
+
+daemon="$ENVLIST /usr/local/bin/brass"
+daemon_user="www"
+daemon_logger="daemon.info"
+
+. /etc/rc.d/rc.subr
+
+pexp=".*/usr/local/bin/brass.*"
+
+rc_bg=YES
+
+rc_cmd $1
+```