diff --git a/README.md b/README.md
index 646ae2e..e869820 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,189 @@
+>
+>
+> ## Caution README in progress
+>
+>
+
 # frontexpress
- 
+
  Minimalist front end router framework a la [express](http://expressjs.com/)
  
  [![Build Status](https://travis-ci.org/camelaissani/frontexpress.svg?branch=master)](https://travis-ci.org/camelaissani/frontexpress)
  [![Coverage Status](https://coveralls.io/repos/github/camelaissani/frontexpress/badge.svg?branch=master)](https://coveralls.io/github/camelaissani/frontexpress?branch=master)
+
+```js
+import frontexpress from 'frontexpress';
+const app = frontexpress();
+
+// listen HTTP GET request on path (/)
+app.get('/', (req, res) => {
+  window.alert('Hello World');
+});
+ 
+// Once DOM is loaded start listening HTTP requests
+document.addEventListener("DOMContentLoaded", (event) => {
+  app.listen();
+});
+```
+
+## Installation
+
+```bash
+$ npm install frontexpress
+```
+
+## Quick Start
+
+ The quickest way to get started with frontexpress is to clone [frontexpress sample](https://github.com/camelaissani/frontexpress) to generate an application as shown below:
+
+ Clone the git repository:
+ 
+```bash
+$ git clone git@github.com:camelaissani/frontexpress-sample.git
+$ cd frontexpress-sample
+```
+
+ Install dependencies:
+
+```bash
+$ npm install
+```
+
+ Start the server:
+
+```bash
+$ npm start
+```
+
+## Tests
+ 
+ Clone the git repository:
+ 
+```bash
+$ git clone git@github.com:camelaissani/frontexpress.git
+$ cd frontexpress
+```
+ 
+ Install the dependencies and run the test suite:
+
+```bash
+$ npm install
+$ npm test
+```
+
+## Routing
+
+### Basic routing
+
+Routing allows to link the frontend application with HTTP requests to a particular URI (or path).
+The link can be specific to an HTTP request method (GET, POST, and so on).
+ 
+The following examples illustrate how to define simple routes.
+ 
+Listen an HTTP GET request on URI (/):
+ 
+```js
+app.get('/', (req, res) => { 
+  window.alert('Hello World'); 
+});
+```
+ 
+Listen an HTTP POST request on URI (/):
+ 
+```js
+app.post('/', (req, res) => { 
+  window.alert('Got a POST request at /'); 
+});
+```
+
+### Route paths
+ 
+Route paths, in combination with a request method, define the endpoints at which requests can be made.
+Route paths can be strings (see basic routing section), or regular expressions.
+ 
+This route path matches all GET request paths which start with (/api/):
+ 
+```js
+app.get(/^api\//, (req, res) => { 
+  console.log(`api was requested ${req.uri}`);
+});
+```
+
+### Route handlers
+
+You can provide multiple callback functions to handle a request. Invoking ```next()``` function allows to pass the control to subsequent routes.
+Whether ```next()``` method is not called the handler chain is stoped
+
+```js
+const h1 = (req, res, next) => { console.log('h1!'); next(); };
+const h2 = (req, res, next) => { console.log('h2!') };
+const h3 = (req, res, next) => { console.log('h3!'); next(); };
+
+app.get('/example/a', h1);
+app.get('/example/a', h2);
+app.get('/example/a', h3);
+```
+
+A response to a GET request on path (/example/a) displays:
+
+```
+h1!
+h2!
+```
+
+h3 is ignored because ```next()``` function was not invoked.
+
+### app.route()
+
+You can create chainable route handlers for a route path by using ```app.route()```.
+
+```js
+app.route('/book')
+ .get((req, res) => { res.send('Get a random book') })
+ .post((req, res) => { res.send('Add a book') })
+ .put((req, res) => { res.send('Update the book') });
+```
+
+### frontexpress.Router
+
+Use the ```frontexpress.Router``` class to create modular, mountable route handlers.
+
+Create a router file named ```birds.js``` in the app directory, with the following content:
+
+```js
+import frontexpress from 'frontexpress';
+
+const router = frontexpress.Router(); 
+
+// middleware that is specific to this router 
+router.use((req, res, next) => {
+  console.log(`Time: ${Date.now()}`); 
+  next(); 
+}); 
+
+// react on home page route 
+router.get('/', function(req, res) => { 
+  document.querySelector('.content').innerHTML = '<p>Birds home page</p>';
+}); 
+
+// react on about route 
+router.get('/about', (req, res) => { 
+  document.querySelector('.content').innerHTML = '<p>About birds</p>'; 
+}); 
+
+export default router;
+```
+
+Then, load the router module in the app:
+
+```js
+import birds  from './birds';
+...
+app.use('/birds', birds);
+```
+
+The app will now be able to react on requests (/birds) and (/birds/about)
+
+## License
+
+ [MIT](LICENSE)