docs

README.md

@@ -288,6 +288,16 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/coinga
 1. Start the RabbitMQ instance via `docker compose up`.
 2. Run `mix test`.
 
+## Architecture
+```mermaid
+  graph TD;
+      A[ApplicationSupervisor - Supervisor] --> B[ConsumerSupervisor - Supervisor];
+      A --> C[ConnectionServer - GenServer];
+      B -- supervises many --> D[ConsumerServer - GenServer];
+      D -- monitors --> E[ConsumerExecutor];
+      E -- sends messages to --> C;
+```
+
 ## License
 
 The library is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

lib/coney/application_supervisor.ex

@@ -1,4 +1,10 @@
 defmodule Coney.ApplicationSupervisor do
+  @moduledoc """
+  Supervisor responsible of `ConnectionServer` and `ConsumerSupervisor`.
+
+  Main entry point of the application.
+  """
+
   use Supervisor
 
   alias Coney.{ConsumerSupervisor, ConnectionServer}

lib/coney/connection_server.ex

@@ -1,4 +1,18 @@
 defmodule Coney.ConnectionServer do
+  @moduledoc """
+  Handles connections between `ConsumerServer` and the RabbitMQ instance(s).
+
+  This module abstracts away the connection status of RabbitMQ. Instead, when
+  a new `ConsumerServer` is started, it requests `ConnectionServer` to open a channel.
+  ConnectionServer opens a real amqp channel, keeps a reference to it in its state and
+  returns an erlang reference to `ConsumerServer`. When `ConsumerServer` replies (ack/reject)
+  an incoming RabbitMQ message it sends the erlang reference to ConnectionServer and then
+  ConnectionServer looks up the real channel.
+
+  ConnectionServer can handle RabbitMQ disconnects independently of ConsumerServer.
+  When connection is lost and then regained, ConnectionServer simply updates its
+  map of {erlang_ref, AMQP.Connection}, ConsumerServer keeps using the same erlang_ref.
+  """
   use GenServer
 
   require Logger

lib/coney/consumer_executor.ex

@@ -1,4 +1,8 @@
 defmodule Coney.ConsumerExecutor do
+  @moduledoc """
+  Module responsible for processing a rabbit message and send the response
+  back to `ConnectionServer`. Started (and monitored) by `ConsumerServer`.
+  """
   require Logger
 
   alias Coney.{ConnectionServer, ExecutionTask}

lib/coney/consumer_server.ex

@@ -1,4 +1,9 @@
 defmodule Coney.ConsumerServer do
+  @moduledoc """
+  GenServer for handling RabbitMQ messages. Spawns and monitors one task per message
+  and forwards the response to `ConnectionServer`.
+  """
+
   use GenServer
 
   alias Coney.{ConnectionServer, ConsumerExecutor, ExecutionTask}

lib/coney/consumer_supervisor.ex

@@ -1,4 +1,7 @@
 defmodule Coney.ConsumerSupervisor do
+  @moduledoc """
+  Supervisor for all ConsumerServer of the application.
+  """
   use Supervisor
 
   alias Coney.ConsumerServer