Improvements

.dialyzer_ignore.exs

@@ -1,5 +1 @@
-[
-  {"test/support/test_scheduler.ex", :pattern_match, 0},
-  {"test/support/test_scheduler.ex", :pattern_match, 2},
-  {"test/support/router.ex", :pattern_match, 16}
-]
+[]

.github/workflows/bless.yml

@@ -54,4 +54,6 @@ jobs:
           mix deps.get
 
       - name: Full bless
-        run: mix bless
+        run: |
+          epmd -daemon
+          mix bless

.tool-versions

@@ -1,2 +1,2 @@
-elixir 1.19.5-otp-28
-erlang 28.3.1
+elixir 1.20.0-otp-29
+erlang 29.0.1

CHANGELOG.md

@@ -1,3 +1,8 @@
+# 0.9.1
+
+- Add set_state optional callback to Aggregate
+- Add documentation.
+
 # 0.9.0
 
 - Breaking change in telemetry events from dispatcher and router
@@ -79,8 +84,8 @@ use X3m.System.MessageHandler,
 
 # 0.7.16
 
-- `execute_on_new_aggregate returns `{:ok, -1}`if aggregate returns`:ok`response
-with empty`events`
+- `execute_on_new_aggregate` returns `{:ok, -1}` if aggregate returns `:ok` response
+  with empty `events`
 
 # 0.7.15
 

README.md

@@ -4,14 +4,88 @@
 [![Hex version](https://img.shields.io/hexpm/v/x3m_system.svg "Hex version")](https://hex.pm/packages/x3m_system)
 [![Coverage Status](https://coveralls.io/repos/github/x3m-ex/system/badge.svg)](https://coveralls.io/github/x3m-ex/system)
 
-Infrastructure building blocks for X3m backend system.
+Building blocks for distributed and/or CQRS/ES systems in Elixir.
+
+`X3m.System` gives you a small set of composable pieces for building message-driven
+backends: a **message** that carries a request and its response, a **router** that
+registers services across a cluster, a **dispatcher** that finds a node offering a
+service and waits for the reply, and — when you need it — **aggregates** with event
+sourcing and a backend-agnostic **scheduler** for delivering messages in the future.
+
+The pieces are **à la carte**. You can use the messaging layer (message + router +
+dispatcher) on its own, add aggregates and event sourcing only where you need them,
+and use the scheduler independently of everything else.
 
 ## Installation
 
 ```elixir
 def deps do
   [
-    {:x3m_system, "~> 0.7.10"}}
+    {:x3m_system, "~> 0.9.1"}
   ]
 end
 ```
+
+One dependency is optional:
+
+- `:elixir_uuid` — needed when working with aggregates (id generation).
+
+## A minimal example
+
+Define a router that registers a service and the module that handles it:
+
+```elixir
+defmodule MyApp.Router do
+  use X3m.System.Router
+
+  service :greet, MyApp.Greeter
+
+  def authorize(_message), do: :ok
+end
+
+defmodule MyApp.Greeter do
+  alias X3m.System.Message
+
+  def greet(%Message{} = message) do
+    name = message.raw_request["name"]
+    {:reply, Message.ok(message, "Hello, #{name}!")}
+  end
+end
+```
+
+Register the services (typically from your application's `start/2`) and dispatch a
+message to the service by name:
+
+```elixir
+:ok = MyApp.Router.register_services()
+
+:greet
+|> X3m.System.Message.new(raw_request: %{"name" => "Ada"})
+|> X3m.System.Dispatcher.dispatch()
+#=> %X3m.System.Message{response: {:ok, "Hello, Ada!"}, ...}
+```
+
+```mermaid
+flowchart LR
+  C[Caller] -->|"Message.new(:greet)"| D[Dispatcher.dispatch]
+  D -->|find a node offering :greet| R[Router]
+  R -->|"authorize/1"| A{authorized?}
+  A -->|no| F["response: {:error, :forbidden}"]
+  A -->|yes| H["Greeter.greet/1"]
+  H -->|"{:reply, Message.ok(...)}"| C
+```
+
+No aggregates or event store are involved here — any module registered through a
+router can be a dispatch target.
+
+## Guides
+
+- [Getting started](guides/getting-started.md) — install, optional deps, your first dispatch.
+- [Messaging](guides/messaging.md) — `Message`, `Router`, `Dispatcher` and the response shapes.
+- [Aggregates & event sourcing](guides/aggregates-and-event-sourcing.md) — `Aggregate`, `MessageHandler`, persisting events, snapshotting and supervision.
+- [Distribution](guides/distribution.md) — service discovery across nodes, choosing the node, and forwarding.
+- [Scheduling](guides/scheduling.md) — persistable, future-dated message delivery with `Scheduler`.
+
+## License
+
+Released under the MIT License. See the [LICENSE](https://github.com/x3m-ex/system/blob/master/LICENSE) file.

coveralls.json

@@ -0,0 +1,8 @@
+{
+  "coverage_options": {
+    "minimum_coverage": 83.0
+  },
+  "skip_files": [
+    "test/support"
+  ]
+}