diff --git a/crates/README.md b/crates/README.md
deleted file mode 100644
index 04909f2..0000000
--- a/crates/README.md
+++ /dev/null
@@ -1,30 +0,0 @@
-## Dependency diagram of the project
-
-```mermaid
-graph TD;
-    lavina-->mgmt-api;
-    lavina-->projection-irc;
-    lavina-->projection-xmpp;
-    lavina-->lavina-core;
-
-    projection-irc-->proto-irc;
-    projection-irc-->lavina-core;
-    
-    projection-xmpp-->proto-xmpp;
-    projection-xmpp-->lavina-core;
-
-    sim-irc-->proto-irc;
-    sim-irc-->mgmt-api;
-
-    sim-xmpp-->proto-xmpp;
-    sim-xmpp-->mgmt-api;
-
-    workspace-->lavina;
-    workspace-->sim-irc;
-    workspace-->sim-xmpp;
-```
-
-A few rules:
-- Only projections should be direct deps of `lavina`, there is no need to depend on `proto-*` crates.
-- On the other hand, projections should not be dependencies of `sim-*` crates.
-- `lavina-core` does not depend on protocol-specific crates.
diff --git a/crates/readme.md b/crates/readme.md
new file mode 100644
index 0000000..93d344a
--- /dev/null
+++ b/crates/readme.md
@@ -0,0 +1,46 @@
+## Dependency diagram of the project
+
+```mermaid
+graph TD;
+    lavina-->mgmt-api;
+    lavina-->projection-irc;
+    lavina-->projection-xmpp;
+    lavina-->lavina-core;
+
+    projection-irc-->proto-irc;
+    projection-irc-->lavina-core;
+    
+    projection-xmpp-->proto-xmpp;
+    projection-xmpp-->lavina-core;
+
+    sim-irc-->proto-irc;
+    sim-irc-->mgmt-api;
+
+    sim-xmpp-->proto-xmpp;
+    sim-xmpp-->mgmt-api;
+
+    workspace-->lavina;
+    workspace-->sim-irc;
+    workspace-->sim-xmpp;
+```
+
+A few rules:
+- Only projections should be direct deps of `lavina`, there is no need to depend on `proto-*` crates.
+- On the other hand, projections should not be dependencies of `sim-*` crates.
+- `lavina-core` does not depend on protocol-specific crates.
+
+## Lavina
+
+**lavina-core**. This crate implements the core functionality of the server not specific to public interfaces. It includes handling general persistence, message casts, in future room authorization and cross-node communication.
+
+**lavina**. The application crate. It's used to link other crates together and build the final binary with support for all protocols.
+
+**mgmt-api**. Model definitions for management API to be used both in the server and client implementations.
+
+## IRC
+
+**proto-irc**. Protocol definition for IRC, includes both server-side and client-side messages and both serialization and deserialization where needed.
+
+**projection-irc**. Projection of lavina-core onto the IRC client-to-server protocol implementation.
+
+**sim-irc**. Future implementation of IRC client simulator to be used in integration and load testing.
diff --git a/docs/cheatsheet.md b/docs/cheatsheet.md
index c74f8c0..1ef20d0 100644
--- a/docs/cheatsheet.md
+++ b/docs/cheatsheet.md
@@ -18,25 +18,12 @@ Print content of a TLS certificate:
 
     openssl x509 -in certs/xmpp.pem -text
 
-Make sure `xmpp.key` starts and ends with:
-```
------BEGIN RSA PRIVATE KEY-----
------END RSA PRIVATE KEY-----
-```
-
-
 ## Protocol Specs
 
 XMPP XSDs - [https://xmpp.org/schemas/index.shtml]
 
 IRC modern spec - [https://modern.ircdocs.horse/]
 
-## Initializing DB with some users
-
-    sqlite3 db.sqlite < test/init_state.sql
-
-Same test migration could be used for integration tests in the future.
-
 ## Using irssi
 
 irssi in a TUI-based IRC client.
diff --git a/docs/running.md b/docs/running.md
new file mode 100644
index 0000000..61f3067
--- /dev/null
+++ b/docs/running.md
@@ -0,0 +1,54 @@
+# Building & Running Lavina
+
+## Configuration
+
+A server instance must be supplied with a configuration file to start up. The path to configuration is specified with a required CLI argument `--config <path>`.
+
+Example configuration:
+```toml
+[telemetry]
+# address for management and telemetry API
+# should be kept private
+listen_on = "127.0.0.1:8080"
+
+[irc]
+listen_on = "127.0.0.1:6667"
+server_name = "irc.localhost"
+
+[xmpp]
+listen_on = "127.0.0.1:5222"
+cert = "./certs/xmpp.pem"
+key = "./certs/xmpp.key"
+
+[storage]
+db_path = "db.sqlite"
+```
+
+## With Docker Compose
+
+Example `docker-compose.yml` file:
+```yaml
+version: '3.0'
+
+services:
+  lavina:
+    image: git.vilunov.me/lavina/lavina:0.0.1
+    volumes:
+      - './config/:/etc/lavina/'
+      - './data/:/var/lib/lavina/'
+    ports:
+      - '5222:5222'  # xmpp
+      - '6667:6667'  # irc non-tls
+      - '127.0.0.1:1380:8080' # management http (private)
+```
+
+## With Cargo
+
+You can run it via cargo:
+
+    cargo run -- --config config.toml
+
+Or you can build it and run manually:
+
+    cargo build --release
+    ./target/release/lavina --config config.toml
diff --git a/readme.md b/readme.md
index 40bb174..a10c043 100644
--- a/readme.md
+++ b/readme.md
@@ -2,6 +2,10 @@
 
 Multiprotocol chat server based on open protocols.
 
+- [How to run Lavina locally](docs/running.md)
+- [Architectural diagrams](docs/flow.md)
+- [Project structure](crates/readme.md)
+
 ## Goals
 
 #### Support for multiple open protocols