Add Technical overview section, do some general reorganization

About-SciNote.md

@@ -2,9 +2,9 @@
 
 ## What is SciNote?
 
-SciNote is a top-rated platform for researchers in academia or industry, who need electronic lab notebook, inventory management and project management functionalities.
+SciNote is a top-rated platform for researchers in academia or industry who need electronic lab notebook, inventory management and project management functionalities.
 
-For more information, visit the [SciNote website](https://scinote.net/).
+For more information, visit the official [SciNote website](https://scinote.net/).
 
 ## What can you do in SciNote?
 

Home.md

@@ -1,8 +1,10 @@
-![sciNote logo](https://scinote.net/wp-content/uploads/2018/05/SciNote-Logo-2018.png)<br><br><br>
+[[images/SciNote-Logo-2018.png]]
+
+<br><br><br>
 
 Welcome to the [**SciNote** - open source electronic lab notebook](http://scinote.net/) ([ELN](https://en.wikipedia.org/wiki/Electronic_lab_notebook)), developed and maintained by SciNote LLC.
 
-This wiki is the main source of documentation for **developers** & **administrators** working with (or contributing to) the SciNote project. For other information please visit [SciNote website](http://scinote.net/).
+This wiki is the main source of technical documentation for **developers** & **administrators** working with (or contributing to) the SciNote project. For other information please visit official [SciNote website](http://scinote.net/).
 
 ## Contents
 

Setup-guide.md

@@ -1,16 +1,20 @@
-## Build & run
+## Technical overview
+
+To view the technical overview of SciNote, its architectural components, and everything related to containerization, visit [Technical overview section](Technical-overview).
+
+## Build & run (development mode)
 
 For instructions on how to build & run SciNote - including minimal **quick-start** setup - visit [Build & run section](Build-&-run).
 
-## Production mode
-
-To host SciNote on a server, and run it in production mode (in Docker containers), visit the [Production mode section](Production-mode).
-
 ## Environmental variables
 
 SciNote is configured using environmental variables. To see list of available variables, and a minimal `application.yml` file, visit [Environmental variables section](Environmental-variables).
 
-## Rake/rails tasks
+## Production mode
+
+To host SciNote on a server, and run it in production mode (in Docker containers), visit the [Production mode section](Production-mode).
+
+## Rake tasks
 
 SciNote server uses `rake`/`rails` tasks for various operations. For details regarding `rake`/`rails` tasks, when to run them and how to set them up, visit the [Rake tasks section](Rake-tasks).
 

Technical-overview.md

@@ -0,0 +1,117 @@
+### Table of Contents
+
+* [Introduction](#user-content-introduction)
+* [Prerequisites](#user-content-prerequisites)
+* [Docker and containers](#user-content-docker-and-containers)
+* [Engines and modularity](#user-content-quick-start)
+
+---
+
+## Introduction
+
+SciNote is primarily designed as a [multi-tenant](https://en.wikipedia.org/wiki/Multitenancy) web application.
+
+SciNote is developed in [Ruby on Rails](http://rubyonrails.org/). It is a [monolithic web application](https://en.wikipedia.org/wiki/Monolithic_application), following Ruby on Rails [guidelines and best practices](https://rubyonrails.org/doctrine/). Some other important technological aspects of the SciNote platform:
+* Back-end is following the Rails's MVC implementation.
+* Front-end comprises of `.html.erb` views, rendered using [server-side rendering](), and [jQuery](https://jquery.com/) JavaScript code that often relies on AJAX calls to trigger dynamic actions to the server. Majority of JavaScript code is local to individual pages.
+* Data is stored within [PostgreSQL](https://www.postgresql.org/), and all files are stored on either filesystem or [Amazon S3](https://aws.amazon.com/s3/).
+* [Less](http://lesscss.org/) is used for CSS pre-processing.
+* [Webpack](https://webpack.js.org/) is used to bundle front-end assets (`.js`, `scss`/`.css`).
+* [Puma](https://github.com/puma/puma) is used as the web application server of choice.
+* Background worker is implemented using [`Delayed::Job`](https://github.com/collectiveidea/delayed_job) gem.
+* See [Gemfile](https://github.com/biosistemika/scinote-web/blob/master/Gemfile) for the list of used technologies.
+
+
+## Prerequisites
+
+These are the minimal technical requirements required to install SciNote server on a computer:
+
+* 512+ MB of dedicated RAM, and a dual-core CPU,
+* OS that supports [Docker](https://www.docker.com) (Mac, Windows or Linux),
+* Makefile (`make`),
+* [Docker](https://www.docker.com/),
+* [docker-compose](https://docs.docker.com/compose/).
+
+As stated above, all major operating systems (Mac, Windows, Linux) support Docker. However, due to the nature of the Docker implementation, as well as the tooling required around SciNote (Makefile, docker-compose), it is **strongly suggested to deploy SciNote on a Linux operating system**.
+
+## Docker and containers
+
+SciNote relies heavily on [Docker](https://www.docker.com/) containers to separate its individual processes & services.
+
+The following separate containers are employed on a running SciNote server:
+
+1. Database data container **(persistent)** hosts all database engine files, and is placed by default into `/var/lib/docker/volumes` folder on the host system;
+2. Files container **(persistent)** stores all generated & uploaded files when SciNote is configured to use local filesystem for storage (`PAPERCLIP_STORAGE` is set to `'filesystem'`);
+3. Database engine container (non-persistent) hosts the database engine process;
+4. Job worker container (non-persistent) hosts the background worker process;
+5. Web worker container (non-persistent) hosts the web application process.
+
+SciNote can be setup to run in various ways, but the following schema provides the most common - *default* - way of how to setup the SciNote containers:
+
+[[images/Docker-Schema.png]]
+
+Generally, all parts of the system can be modified; PostgreSQL engine, as well as the database data, can also reside outside the Docker containers; similarily, load balancing could also be done on the containerized Puma server; due to the containerized nature of the setup, any container can be pulled out and hosted in a different manner.
+
+
+
+## Engines and modularity
+
+To achieve a level of modularity/extensibility, SciNote introducec a concept of **addons**. Modularity in the sense that additional features can be bundled alongside SciNote core in the form of addons. An addon is simply a [Rails engine](http://guides.rubyonrails.org/engines.html) that adds/modifies functionalities of SciNote core (like e.g. [Wordpress plugins](https://wordpress.org/plugins/)).
+
+Addons can be used to introduce new, toggle-able functionalities into SciNote at build-time. Often, however, addons will want to have some stitching points with SciNote core, which inherently means that they require to modify some of the SciNote core codebase (e.g. addons inject some of their components into existing SciNote core codebase). This is achieved by using the following methods:
+* `ActiveRecord` models are modified using decorator pattern (using `class_eval`);
+* `Controller`-s are modified using decorator pattern (using `class_eval`);
+* `.erb` templates are modified using Ruby Gem called [Deface](https://github.com/spree/deface);
+* `JavaScript` code is modified in different ways; but mostly, a new `.js` file is contained with the addon, and referenced from the injected `.erb` view.
+
+On an architectural level, all addons are - inherently - dependant on SciNote core, but they can also be dependant on one another.
+
+The addons are packaged alongside SciNote at a build/deployment time. This means that once the SciNote (actually, Rails server) starts, the addons are loaded alongside SciNote core, and further modification while the server is running are not possible. This is what is meant by build-time modularity:
+
+```
++-----------------------------------------------+
+|  SCINOTE                                      |
+|                                               |
+|   SciNote core      addon #1   addon #2   ... |
+| +----------------++----------+----------+     |
+| |    frontend    || frontend | frontend |     |
+| |  __    __    __||  __    __|  __    __| ... |
+| |_/  \__/  \__/  ||_/  \__/  |_/  \__/  |     |
+| |    backend     || backend  | backend  |     |
+| +----------------++----------|----------|     |
++-----------------------------------------------+
+```
+
+To add an addon to a SciNote deployment, the following basic steps need to be done:
+
+* Addon source code must be added as a folder under:
+
+  ```bash
+  <scinote_root_dir>/addons/<my_addon>
+  ```
+
+* Inside `Gemfile`, following reference must be added:
+
+  ```ruby
+  gem '<my_addon>', path: 'addons/<my_addon>'
+  ```
+
+* (If neccesary) Add the following reference inside `config/routes.rb`:
+
+  ```ruby
+  mount My::Addon::Engine => '/'
+  ```
+
+* (If neccesary) Add the following reference inside `app/assets/javascripts/application.js.erb`:
+
+  ```js
+  //= require my/addon
+  ```
+
+* (If neccesary) Add the following reference inside `app/assets/stylesheets/application.scss` (starting comment):
+
+  ```css
+   *= require my/addon/application
+  ```
+
+Of course, additional steps might need to be done (e.g. configuring the addon via the initializer, etc.).

_Sidebar.md

@@ -1,11 +1,10 @@
 [Home](home)
 * [About SciNote](about-scinote)
-  * [What is SciNote?](about-scinote#what-is-scinote)
-  * [What can you do in SciNote?](about-scinote#what-can-you-do-in-scinote)
 * [Setup guide](setup-guide)
+  * [Technical overview](Technical-overview)
   * [Build & run](Build-&-run)
   * [Environmental variables](Environmental-variables)
-  * [Production mode (in Docker containers)](Production-mode)
+  * [Production mode](Production-mode)
   * [Rake tasks](Rake-tasks)
   * [Mailer](setup-guide#mailer)
   * [Office Online integration](setup-guide#office-online-integration)