Add documentation

README.md

@@ -1,18 +1,60 @@
-# BirdyChat
+# BirdyChat Tech Challenge
 
-To start your Phoenix server:
+This repository implements BirdyChat tech challenge.
 
-* Run `mix setup` to install and setup dependencies
-* Start Phoenix endpoint with `mix phx.server` or inside IEx with `iex -S mix phx.server`
+# Start here
 
-Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
+Firstly, check out this repository locally.
+Then install required versions of Elixir and Erlang from .tool-versions. asdf-vm will pick them up automatically.
+Then you run the test suite with `mix test`.
+Then, a scripted demo release is prepared in the prod environment:
 
-Ready to run in production? Please [check our deployment guides](https://hexdocs.pm/phoenix/deployment.html).
+```
+MIX_ENV=prod mix build_release
+```
 
-## Learn more
+Then you can run 3 servers connected to one another:
 
-* Official website: https://www.phoenixframework.org/
-* Guides: https://hexdocs.pm/phoenix/overview.html
-* Docs: https://hexdocs.pm/phoenix
-* Forum: https://elixirforum.com/c/phoenix-forum
-* Source: https://github.com/phoenixframework/phoenix
+`_build/prod/rel/birdy_chat/bin/server_1` - runs at localhost:4001
+`_build/prod/rel/birdy_chat/bin/server_2` - runs at localhost:4002
+`_build/prod/rel/birdy_chat/bin/server_3` - runs at localhost:4003
+
+Out of the box they communicate with one another. Send a json request to one of them and observe the results. Feel free to modify the examples below.
+
+### A local request:
+
+```
+curl --request POST \
+  --url http://localhost:4001/api/messages \
+  --header 'content-type: application/json' \
+  --data '{"message":"123","to":"1-user","from":"1-user"}'
+```
+
+### A remote request:
+
+```
+curl --request POST \
+  --url http://localhost:4001/api/messages \
+  --header 'content-type: application/json' \
+  --data '{"message":"123","to":"2-user","from":"1-user"}'
+```
+
+### A request to unknown server:
+
+```
+curl --request POST \
+  --url http://localhost:4001/api/messages \
+  --header 'content-type: application/json' \
+  --data '{"message":"123","to":"4-user","from":"1-user"}'
+```
+
+Files are saved to `priv/messages`.
+
+
+## Key rundown of technical details
+
+First and foremost, I tried to keep it as simple as possible - stick to know conventions, leverage existing libraries or frameworks, hence the usage of both Phoenix and Ecto - conventions they provide are understandable to pretty much any Elixir developer.
+
+All important modules are documented and there is a test suite that exacutes all known code paths.
+
+Servers authenticate with one another using Phoenix tokens. Servers communicate via HTTP using JSON. There were other options but I decided to use this one for reasons enumerated in documentation for BirdyChatWeb.Api.Server.Internal.Controller.