feat(docs): add project structure and best practices

CONTRIBUTING.md

@@ -2,9 +2,14 @@
 
 Thanks for showing interest in contributing!
 
-The following is a set of guidelines for contributing to the Stencil CLI. These are just guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
+The following is a set of guidelines for contributing to the Stencil CLI. These are just guidelines, not rules.
+Use your best judgment, and feel free to propose changes to this document in a pull request.
 
-By contributing to Stencil CLI, you agree that your contributions will be licensed as listed under the [README.md](https:/bigcommerce/stencil-cli/blob/master/README.md).
+At the moment some parts of the project may be outdated and not follow these recommendations.
+They should be gradually refactored with time.
+
+By contributing to Stencil CLI, you agree that your contributions will be licensed as listed under the 
+[README.md](https:/bigcommerce/stencil-cli/blob/master/README.md).
 
 #### Table of Contents
 
@@ -13,21 +18,36 @@ By contributing to Stencil CLI, you agree that your contributions will be licens
 [How Can I Contribute?](#how-can-i-contribute)
  * [Your First Code Contribution](#your-first-code-contribution)
  * [Pull Requests](#pull-requests)
+ * [Release stencil-cli](#release-stencil-cli)
 
 [Styleguides](#styleguides)
  * [Git Commit Messages](#git-commit-messages)
  * [JavaScript Styleguide](#javascript-styleguide)
+ * [Project best practices](#project-best-practices)
+
+[Implementation details](#implementation-details)
+ * [Project structure](#project-structure)
+
+## How Can I Contribute?
 
 ### Your First Code Contribution
 
-Unsure where to begin contributing to Stencil CLI? Check our [forums](https://forum.bigcommerce.com/s/group/0F91300000029tpCAA) or our [stackoverflow](https://stackoverflow.com/questions/tagged/bigcommerce) tag. 
+Unsure where to begin contributing to Stencil CLI? Check our [forums](https://forum.bigcommerce.com/s/group/0F91300000029tpCAA),
+[Github issues](https:/bigcommerce/stencil-cli/issues), or our
+[stackoverflow](https://stackoverflow.com/questions/tagged/bigcommerce) tag. 
 
 ### Pull Requests
 
 * Fill in [the required template](https:/bigcommerce/stencil-cli/pull/new/master)
 * Include screenshots and animated GIFs in your pull request whenever possible.
 * End files with a newline.
 
+### Release stencil-cli
+In order to release stencil-cli you should first use the `Squash and merge` option on GitHub, This step is important
+for generating the `CHANGELOG.md` file with the PR link attached (if not using `Squash and merge`, the changes will
+be logged only with links to the commits). After the changes are merged to master, pull the latest to your local
+environment, run `gulp release` and follow the prompts.
+
 ## Styleguides
 
 ### Git Commit Messages
@@ -41,3 +61,41 @@ Unsure where to begin contributing to Stencil CLI? Check our [forums](https://fo
 ### JavaScript Styleguide
 
 All JavaScript must adhere to [AirBnB Javascript Styleguide](https:/airbnb/javascript).
+
+Additionally:
+- Prefer async/await to callbacks.
+- Class dependencies with side effects (e.g. "fs" has side effects, "lodash" - hasn't) should be
+explicitly passed to the constructor so that they can be mocked in unit tests.
+
+### Project best practices
+
+**CLI commands:**
+
+Entry point is located at `/bin`. The file with entry point should only read the CLI arguments and
+call a corresponding CLI-command-class with the implementation located at `/lib`. CLI-command-class uses
+dependency injection throughout constructor, the main method runs other methods-tasks. Tasks are aimed to be pure and
+use context (this) only for external dependencies (logger, fs, etc).
+
+Shared logic and tasks should be moved out from the CLI-command-classes to separate service classes.
+
+E.g.: [stencil-init](/bin/stencil-init).
+
+**Local server:**
+
+Hapi server plugins located at `/server/plugins` should have controller logic only. Business logic should be moved out to
+common entities located at `/lib`.
+
+## Implementation details
+
+### Project structure
+
+```
+.
+├── .github Templates for github documents
+├── bin Entry points for CLI commands
+├── server Local server
+├── tasks Gulp tasks
+├── test Common entities and helpers used for tests
+├── lib Source code for all other entities
+└── constants.js Common constants
+```

README.md

@@ -1,7 +1,8 @@
 # Stencil CLI
 
-[![npm (scoped)](https://img.shields.io/npm/v/@bigcommerce/stencil-cli.svg)](https://www.npmjs.com/package/@bigcommerce/stencil-cli) [![Travis](https://travis-ci.org/bigcommerce/stencil-cli.svg?branch=master)](https://travis-ci.org/bigcommerce/stencil-cli) [![AppVeyor](https://ci.appveyor.com/api/projects/status/jejnlajci3dslwfx?svg=true)](https://ci.appveyor.com/project/BigCommerceEngineering/stencil-cli)
-
+[![npm (scoped)](https://img.shields.io/npm/v/@bigcommerce/stencil-cli.svg)](https://www.npmjs.com/package/@bigcommerce/stencil-cli) 
+[![Travis](https://travis-ci.org/bigcommerce/stencil-cli.svg?branch=master)](https://travis-ci.org/bigcommerce/stencil-cli) 
+[![AppVeyor](https://ci.appveyor.com/api/projects/status/jejnlajci3dslwfx?svg=true)](https://ci.appveyor.com/project/BigCommerceEngineering/stencil-cli)
 
 The BigCommerce server emulator for local theme development.
 
@@ -10,7 +11,8 @@ _Note: Stencil requires the Node.js runtime environment, version 10.x We do not
 
 Run `npm install -g @bigcommerce/stencil-cli`.
 
-Visit the [installation guide](https://developer.bigcommerce.com/stencil-docs/getting-started/installing-stencil) for more details.
+Visit the [installation guide](https://developer.bigcommerce.com/stencil-docs/getting-started/installing-stencil)
+for more details.
 
 ## Usage
 
@@ -38,23 +40,34 @@ Run `stencil start` to run a local server so you can start developing your theme
 
 Run with `-o` or `--open` to automatically open up a browser.
 
-- While stencil is running, you can type "rs" and then hit enter to auto-reload all browsers. This is similar to Nodemon's rs option.
+- While stencil is running, you can type "rs" and then hit enter to auto-reload all browsers. This is similar to
+Nodemon's rs option.
 
 Run `stencil bundle` to validate your code and create a zip bundle file that can be uploaded to BigCommerce.
 
-Run `stencil release` to tag a new version of your theme, create a [GitHub release](https://help.github.com/articles/about-releases/) in your theme repository, and upload the zip bundle file to the release assets. This is useful for tracking your changes in your Theme, and is the tool we use to create new releases in BigCommerce [Cornerstone](https:/bigcommerce/stencil) theme.
+Run `stencil release` to tag a new version of your theme, create a [GitHub release](https://help.github.com/articles/about-releases/)
+in your theme repository, and upload the zip bundle file to the release assets.
+This is useful for tracking your changesin your Theme, and is the tool we use to create new releases in BigCommerce
+[Cornerstone](https:/bigcommerce/stencil) theme.
+
+## Features
 
-## BrowserSync
+### BrowserSync
 
-Stencil CLI comes packaged with BrowserSync so you can take advantage of all of those amazing goodies! Have a look at their [web site](http://www.browsersync.io/) for more information.
+Stencil CLI comes packaged with BrowserSync so you can take advantage of all of those amazing goodies!
+Have a look at their [web site](http://www.browsersync.io/) for more information.
 
-## Sass compiling
+### Sass compiling
 
-You can compile Sass (node-sass) scss files in assets/scss into CSS. For example, add an scss file named theme.scss to assets/scss and `{{{stylesheet 'assets/css/theme.css'}}}` to your theme HTML template. Stencil-CLI will compile assets/scss/theme.scss to CSS on the fly.
+You can compile Sass (node-sass) scss files in assets/scss into CSS. For example, add an scss file named theme.scss
+to assets/scss and `{{{stylesheet 'assets/css/theme.css'}}}` to your theme HTML template. Stencil-CLI will compile
+assets/scss/theme.scss to CSS on the fly.
 
-## Autoprefixer
+### Autoprefixer
 
-Stencil CLI comes packaged with [Autoprefixer](https:/postcss/autoprefixer). You can set which browsers should be targeted, as well as if it should cascade the generated rules in the theme's config.json file with these options:
+Stencil CLI comes packaged with [Autoprefixer](https:/postcss/autoprefixer). You can set which browsers
+should be targeted, as well as if it should cascade the generated rules in the theme's config.json file with these
+options:
 
 - `autoprefixer_cascade` - Defaults to `true`.
 - `autoprefixer_browsers` - Defaults to `["> 1%", "last 2 versions", "Firefox ESR"]`.
@@ -63,8 +76,10 @@ Stencil CLI comes packaged with [Autoprefixer](https:/postcss/autopr
 
 If you need any help or experience any bugs, please create a GitHub issue in this repository.
 
-## Release stencil-cli
-In order to release stencil-cli you should first use the `Squash and merge` option on GitHub, This step is important for generating the `CHANGELOG.md` file with the pr link attached (if not using `Squash and merge`, the changes will be logged only with links to the commits). After the changes are merged to master, pull the latest to your local environment, run `gulp release` and follow the prompts. NOTE: It is required that all commit messages follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.2/) structure.
+## Development
+
+If you would like to improve this project check out the [Contributing Guide](./CONTRIBUTING.md). Also, you can find
+the implementation details there.
 
 ## License