From 6dfd17ff87fda4c32b7e3f66cf569d12c3bc73c7 Mon Sep 17 00:00:00 2001
From: Christoffer Niska <christofferniska@gmail.com>
Date: Sat, 24 Feb 2018 11:11:03 +0200
Subject: [PATCH] Update README.md

---
 README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/README.md b/README.md
index 7afb4b92..ebda246f 100644
--- a/README.md
+++ b/README.md
@@ -5,3 +5,75 @@
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/digiaonline/graphql-php/master/LICENSE)
 
 A PHP7 implementation of the [GraphQL specification](http://facebook.github.io/graphql/).
+
+## Requirements
+
+- PHP version >= 7.1
+
+## Motivation
+
+When we started developing this project there was two GraphQL implementations available for PHP developers; one from 
+[Webonyx](https://github.com/webonyx/graphql-php/) and one from [Youshido](https://github.com/youshido/graphql/).
+Both of these had their own problems. The one from Webonyx is pretty much a direct port from the 
+[JavaScript implementation](https://github.com/graphql/graphql-js/) and includes a lot of things that we thought
+should be provided as separate, optional libraries. The other implementation from Youshido was not a port and had some 
+neat ideas, but unfortunately it did not fulfill the GraphQL specification. In addition to this both of the libraries 
+were started quite a long time ago and are mainly developed by a single person (based on the commit log).
+After looking into these alternatives, we knew that we could do better.
+
+TODO
+
+## Architecture
+
+### Packages
+
+#### Execution
+
+Takes care of executing operation against a GraphQL schema.
+
+**Package lead: [@hungneox](https://github.com/hungneox/)**
+
+### Language
+
+Defines the GraphQL language and the associated AST.
+
+**Package lead: [@crisu83](https://github.com/crisu83/)**
+
+#### Parsing
+
+The plan is to encourage developers to use the official GraphQL parser written C++ through a PHP extension because
+its performance is outstanding. However, we will also provide a shim for the parser, which allows developers to use 
+this library without installing a custom PHP extension in their environment.
+
+The official GraphQL parser takes a GQL string as its input and returns the corresponding Abstract Syntax Tree (AST)
+(an associative array in PHP) as its output. Most of the GraphQL implementations (across all languages) takes a
+different approach where they convert the AST directly into nodes (class instances in PHP). While this approach might 
+be a bit faster, it couples the parser tightly with the rest of the library, which we think is short-sighted. 
+Instead we decided to take a different approach, where the parser produces the AST as an associative array. This allows 
+the developers to switch out the bundled parser for the parser written in C++ without changing a single line of code.
+
+#### AST representation
+
+We also believe that all libraries should be easy to extend so we decided to introduce a builder system using the 
+Builder pattern for converting the AST into nodes. This approach allows developers to implement their own builders if 
+the specification would change in the future, without changing a single line of code in this library.
+
+### Type system
+
+Describes the GraphQL type system and schema definition.
+
+**Package lead: [@crisu83](https://github.com/crisu83/)**
+
+TODO
+
+## Usage
+
+TODO
+
+## Contributing
+
+TODO
+
+## License
+
+See [LICENCE](LICENSE).