Improve README

Author: pedroperrone

.circleci/config.yml

@@ -3,7 +3,7 @@ version: 2.1
 defaults: &defaults
   working_directory: ~/listify
   docker:
-    - image: circleci/elixir:1.9.4
+    - image: circleci/elixir:1.10.1
     - image: postgres:latest
       environment:
           POSTGRES_USER: postgres

README.md

@@ -2,19 +2,45 @@
 
 # Listify
 
-To start your Phoenix server:
+This repository contains the implementation of a simple shopping list. It has both a UI built with LiveView and a REST API.
 
-  * Setup the project with `mix setup`
-  * Start Phoenix endpoint with `mix phx.server`
+## Dependencies
 
-Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
+To run the project and its tests, the following dependencies are required:
+* Elixir 1.10
+* Postgres 11+
 
-Ready to run in production? Please [check our deployment guides](https://hexdocs.pm/phoenix/deployment.html).
+## Running the project
 
-## Learn more
+To run the project, first export the following environment variables regarding your database configuration:
+* `DATABASE_USERNAME` - Defaults to `postgres`
+* `DATABASE_PASSWORD` - Defaults to `postgres`
+* `DATABASE_NAME` - Defaults to `listify_dev`
+* `DATABASE_POOL_SIZE` - Defaults to `10`
 
-  * 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
+Then, navigate to the cloned repository and run the following commands:
+```shell
+mix deps.get
+mix ecto.setup
+mix phx.server
+```
+
+The project will be available on `localhost:4000`. The list is under the route `/items`.
+
+## Running unit tests
+
+The library used to build unit tests was `ExUnit`. In assistance to it, `ExMachina` was used to build factories.
+
+To run the tests, first export the database credentials and name (here the default name changed to `listify_test`) and then use the command `mix test`.
+
+## Static code analysis
+
+Two tools were set in the project: `Credo`, which is focused on code consistency and refactor opportunities, and `Dialyzer`, which is focused on identifying software discrepancies, such as definite type errors, code that has become dead or unreachable because of programming error. To run them, use the commands
+```shell
+mix credo
+mix dialyzer
+```
+
+## Architecture
+
+In order to avoid code duplication in the full stack application and in the API, the concept of [use cases](http://www.plainionist.net/Implementing-Clean-Architecture-UseCases/) was implemented. The use cases are the intermediate between the business rules and the presenters, which are the controllers and the LiveView modules.

config/dev.exs

@@ -2,12 +2,12 @@ use Mix.Config
 
 # Configure your database
 config :listify, Listify.Repo,
-  username: "postgres",
-  password: "postgres",
-  database: "listify_dev",
+  username: System.get_env("DATABASE_USERNAME", "postgres"),
+  password: System.get_env("DATABASE_PASSWORD", "postgres"),
+  database: System.get_env("DATABASE_NAME", "listify_dev"),
   hostname: "localhost",
   show_sensitive_data_on_connection_error: true,
-  pool_size: 10
+  pool_size: String.to_integer(System.get_env("DATABASE_POOL_SIZE", "10"))
 
 # For development, we disable any cache and enable
 # debugging and code reloading.

config/test.exs

@@ -6,9 +6,10 @@ use Mix.Config
 # to provide built-in test partitioning in CI environment.
 # Run `mix help test` for more information.
 config :listify, Listify.Repo,
-  username: "postgres",
-  password: "postgres",
-  database: "listify_test#{System.get_env("MIX_TEST_PARTITION")}",
+  username: System.get_env("DATABASE_USERNAME", "postgres"),
+  password: System.get_env("DATABASE_PASSWORD", "postgres"),
+  database:
+    System.get_env("DATABASE_NAME", "listify_test#{System.get_env("MIX_TEST_PARTITION")}"),
   hostname: "localhost",
   pool: Ecto.Adapters.SQL.Sandbox
 

mix.exs

@@ -8,7 +8,7 @@ defmodule Listify.MixProject do
         plt_file: {:no_warn, "priv/plts/dialyzer.plt"}
       ],
       version: "0.1.0",
-      elixir: "~> 1.7",
+      elixir: "~> 1.10",
       elixirc_paths: elixirc_paths(Mix.env()),
       compilers: [:phoenix, :gettext] ++ Mix.compilers(),
       start_permanent: Mix.env() == :prod,