diff --git a/README.md b/README.md
index 5dad723f0f0a95c67e0e573e6193f0b7aad56ab7..03fa5f1aa2e4ce69addb4d9bef8552fb3871726d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,34 @@
-This is the administration system for VIPS. It relies on a PostgreSQL database. 
-The DDL files for this database are not in this repository, but can be obtained
-by a request to NIBIO.
\ No newline at end of file
+# VIPSLogic
+
+Tor-Einar Skog, NIBIO
+
+Last update: 2021-02-03
+
+## Overview
+VIPSLogic is the administration and business logic system of VIPS. Its main functionalities are:
+
+* Batch running of models 
+* Caching/storing results from batch runs
+* Database of field pest observations
+* Management of organizations, users, farmer's fields, crops, pests and weather data sources
+* Messaging / subscription services
+* Web services to support VIPS's own public web pages and 3rd party clients
+
+No models are deployed in VIPSLogic. It depends on web services from VIPSCore/VIPSCoreManager to run the models. However, for each model available in the VIPSCore/VIPSCoreManager system VIPSLogic needs a preprocessor to compile the model specific input data.
+
+VIPSLogic is the source of data for most clients, including VIPSWeb, the standard public web page for a VIPS system. 
+
+![How VIPSLogic fits into the whole VIPS architecture](./docs/illustrations/VIPS_whole_architecture.png "All VIPS system parts")
+
+## Technical description
+### Environment that VIPSLogic is confirmed to work within
+* Operating system: Ubuntu Linux >= 18.0.4 
+* Database: PostgreSQL >= 10  + PostGIS >= 2.4
+* Java: OpenJDK >= 11
+* Java EE application server: Wildfly >= 16
+
+## License
+VIPSLogic is licensed under the [NIBIO Open Source License](https://nibio.no/licenses), which is basically the [GNU Affero GPL v3 license](https://www.gnu.org/licenses/agpl-3.0.en.html).
+
+## Develop and deploy VIPSLogic
+Please read [the developer documentation](./docs/index.md)
\ No newline at end of file
diff --git a/docs/illustrations/VIPS_whole_architecture.png b/docs/illustrations/VIPS_whole_architecture.png
new file mode 100644
index 0000000000000000000000000000000000000000..6b4f1d748bac1f713206b8204ce343a000883f02
Binary files /dev/null and b/docs/illustrations/VIPS_whole_architecture.png differ
diff --git a/docs/index.md b/docs/index.md
index b77af84052f9718bce03b34af7dbb5b39149ad51..69f0b91b3bf9fdeffd2bac305acf8c58275b4b03 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -2,7 +2,7 @@
 ## But first: A deployment note
 Whether you deploy using Docker or Wildfly (or another JEE server), the context path of the app is always /VIPSLogic. However, the app is designed to be accessible at the root level. So you always need to proxy it behind e.g. Apache or Nginx. Here's an example vhost for Apache:
 
-```
+``` apache
 <VirtualHost *:80>
         ServerName vipslogic-local.no
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index cb7c88365b8fa317b1e16139681ed9fc05949169..66a3f23975089a1e88ca63798d533b62c6cda3f6 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1,6 +1,7 @@
-#Troubleshooting
+# Troubleshooting
+Various tips and tricks for fixing problems are added here
 
-##Transaction timeouts
+## [2021] Transaction timeouts
 If you get weird errors when running jobs, e.g. like this:
 
 ```