Elixir / Phoenix Patterns

Patterns canoniques pour construire des applications web temps-réel et fault-tolerant avec Elixir + Phoenix + OTP.

1. Pourquoi Elixir/Phoenix ?

Use case	Elixir/Phoenix vs alternative
Chat / collab temps-réel	Phoenix LiveView + Channels + Presence > Node.js + Socket.IO
Backend IoT massivement concurrent	BEAM VM lightweight processes > tout
Fault tolerance distribué	OTP supervisors > custom retry/circuit-breaker
Server-rendered SPA-like UX	LiveView > React + WebSocket sync custom
Streaming data pipelines	GenStage + Broadway > Apache Kafka Streams
Soft real-time gaming backend	BEAM > Node/Go (1M+ connections par node)
Apps simples CRUD	Postgres + Rails / Django > Phoenix (overkill)

Règle : Phoenix brille quand tu as besoin de temps-réel + fault tolerance + concurrence massive simultanément. Pour du CRUD basique, Rails/Django sont plus rapides à développer.

2. Setup Phoenix

# Install Elixir + Erlang
brew install elixir

# Install Phoenix
mix archive.install hex phx_new

# Create project
mix phx.new my_app --database postgres --live  # avec LiveView
cd my_app
mix ecto.create
mix phx.server

Structure :

my_app/
├── config/                    # config par env
├── lib/
│   ├── my_app/                # business logic (contexts)
│   │   ├── accounts/          # context: user accounts
│   │   │   ├── user.ex        # Ecto schema
│   │   │   └── ...
│   │   ├── catalog/           # context: products
│   │   └── application.ex     # OTP application + supervision tree
│   └── my_app_web/            # web layer (router, controllers, views)
│       ├── controllers/
│       ├── components/
│       ├── live/              # LiveView pages
│       ├── router.ex
│       └── endpoint.ex
├── priv/repo/migrations/      # DB migrations
├── test/
└── mix.exs

3. OTP — GenServer + Supervisor

# lib/my_app/cache_server.ex
defmodule MyApp.CacheServer do
  use GenServer

  # Client API
  def start_link(opts) do
    GenServer.start_link(__MODULE__, %{}, name: __MODULE__)
  end

  def get(key), do: GenServer.call(__MODULE__, {:get, key})
  def put(key, value), do: GenServer.cast(__MODULE__, {:put, key, value})

  # Server callbacks
  @impl true
  def init(state), do: {:ok, state}

  @impl true
  def handle_call({:get, key}, _from, state) do
    {:reply, Map.get(state, key), state}
  end

  @impl true
  def handle_cast({:put, key, value}, state) do
    {:noreply, Map.put(state, key, value)}
  end
end

# lib/my_app/application.ex
defmodule MyApp.Application do
  use Application

  @impl true
  def start(_type, _args) do
    children = [
      MyApp.Repo,
      MyAppWeb.Endpoint,
      MyApp.CacheServer,           # ajouté à la supervision tree
      {Phoenix.PubSub, name: MyApp.PubSub},
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

Si CacheServer crash, le supervisor le restart automatiquement → "Let it crash" philosophy.

4. Contexts (bounded subdomains)

# lib/my_app/accounts.ex
defmodule MyApp.Accounts do
  alias MyApp.Repo
  alias MyApp.Accounts.User

  def list_users, do: Repo.all(User)

  def get_user!(id), do: Repo.get!(User, id)

  def create_user(attrs \\ %{}) do
    %User{}
    |> User.changeset(attrs)
    |> Repo.insert()
  end

  def update_user(%User{} = user, attrs) do
    user
    |> User.changeset(attrs)
    |> Repo.update()
  end

  def delete_user(%User{} = user), do: Repo.delete(user)
end

Le context est le seul point d'entrée pour les opérations sur ce domaine. Le controller appelle MyApp.Accounts.create_user(params), il ne touche pas au schema directement.

5. Phoenix LiveView (reactive sans JavaScript)

# lib/my_app_web/live/counter_live.ex
defmodule MyAppWeb.CounterLive do
  use MyAppWeb, :live_view

  @impl true
  def mount(_params, _session, socket) do
    {:ok, assign(socket, count: 0)}
  end

  @impl true
  def handle_event("increment", _params, socket) do
    {:noreply, update(socket, :count, &(&1 + 1))}
  end

  @impl true
  def render(assigns) do
    ~H"""
    <div class="p-4">
      <h1 class="text-2xl">Count: <%= @count %></h1>
      <button phx-click="increment" class="bg-blue-500 text-white px-4 py-2 rounded">
        +1
      </button>
    </div>
    """
  end
end

Tout ce code tourne côté serveur. Quand l'user clique, Phoenix envoie l'event via WebSocket, met à jour @count, re-render le HTML, et envoie le diff au browser. Zéro ligne de JS écrite par l'utilisateur.

LiveView est plus simple et souvent plus performant qu'une SPA React pour 80% des use cases.

6. Channels (real-time pub/sub)

# lib/my_app_web/channels/room_channel.ex
defmodule MyAppWeb.RoomChannel do
  use MyAppWeb, :channel

  @impl true
  def join("room:" <> room_id, _params, socket) do
    {:ok, assign(socket, :room_id, room_id)}
  end

  @impl true
  def handle_in("new_message", %{"body" => body}, socket) do
    broadcast!(socket, "new_message", %{body: body, user: socket.assigns.user_id})
    {:reply, :ok, socket}
  end
end

Côté JS client (le seul endroit où on a besoin d'un peu de JS) :

import { Socket } from "phoenix"
const socket = new Socket("/socket", { params: { token: jwt } })
socket.connect()
const channel = socket.channel("room:42", {})
channel.join()
channel.on("new_message", payload => console.log(payload))
channel.push("new_message", { body: "Hello" })

7. Ecto (DB) avec migrations + multi

# priv/repo/migrations/20260408_create_users.exs
defmodule MyApp.Repo.Migrations.CreateUsers do
  use Ecto.Migration

  def change do
    create table(:users) do
      add :email, :string, null: false
      add :name, :string, null: false
      timestamps()
    end

    create unique_index(:users, [:email])
  end
end

# Multi-step transaction
alias Ecto.Multi

result =
  Multi.new()
  |> Multi.insert(:user, User.changeset(%User{}, params))
  |> Multi.insert(:profile, fn %{user: user} ->
    Profile.changeset(%Profile{user_id: user.id}, %{})
  end)
  |> Multi.run(:welcome_email, fn _repo, %{user: user} ->
    MyApp.Mailer.send_welcome(user)
  end)
  |> MyApp.Repo.transaction()

Si n'importe quelle étape échoue, toute la transaction est rollback.

8. Oban (background jobs)

mix deps.get oban

# lib/my_app/workers/email_worker.ex
defmodule MyApp.Workers.EmailWorker do
  use Oban.Worker, queue: :emails, max_attempts: 5

  @impl Oban.Worker
  def perform(%Oban.Job{args: %{"user_id" => user_id}}) do
    user = MyApp.Accounts.get_user!(user_id)
    MyApp.Mailer.send_welcome(user)
  end
end

# Enqueue
%{user_id: user.id}
|> MyApp.Workers.EmailWorker.new()
|> Oban.insert()

Oban stocke les jobs dans Postgres (pas Redis), ce qui simplifie la stack et donne des features advanced (cron jobs, unique jobs, recurring, retries).

9. Releases (production deploy)

mix release
# → _build/prod/rel/my_app/bin/my_app start

Une release Elixir contient :

• Le code compilé
• Le runtime BEAM VM embedded
• Les configs runtime
• Les scripts de start/stop/migrate

Pas besoin d'Elixir installé sur le serveur cible — la release est self-contained.

# Sur le serveur prod
./bin/my_app eval "MyApp.Release.migrate()"
./bin/my_app start

10. Anti-patterns

1. Pas de Supervisor sur les GenServers — perte d'état au crash
2. GenServer pour de la donnée mutable partagée massive — préférer ETS
3. Fonctions avec side effects dans des pipes — pipes doivent être pure
4. Pas de typespec + Dialyzer — bugs runtime évitables
5. Channels sans auth dans join/3 — accès libre aux rooms
6. Pas de rate limit sur LiveView events — DoS facile
7. Multi sans rollback test — transactions partielles en prod
8. Ecto query N+1 — utiliser Repo.preload([:relation])
9. Pas de mix release — install Elixir partout en prod
10. Hot code upgrades en prod sans tests — risqué
11. Configs hardcodées au lieu de runtime config — pas portable
12. Pas de telemetry — invisible en prod

Checklist livraison

• Elixir 1.16+ + OTP 26+
• Phoenix 1.7+ avec LiveView si besoin reactive UI
• Ecto migrations versionnées
• Contexts comme seul point d'entrée business logic
• OTP supervision tree complet
• Oban pour les background jobs
• Telemetry + Telemetry Metrics + Phoenix LiveDashboard
• Dialyzer en CI
• ExUnit + property tests (PropCheck / StreamData)
• mix release pour prod
• Health endpoint + readiness probe
• Logging structured (JSON)
• Sentry pour error tracking

Quand déléguer

• LiveView UI patterns → ce skill
• Architecture backend cross-langage → agent api-designer (ce plugin)
• Real-time WebSocket sans Elixir → skill realtime-websocket (ce plugin)
• Deploy Phoenix release → skills deploy-railway ou deploy-fly (atum-workflows)
• Tests avancés → skill property-based-testing (ce plugin)

Ressources

• https://hexdocs.pm/phoenix/
• https://hexdocs.pm/phoenix_live_view/
• https://hexdocs.pm/ecto/
• https://hexdocs.pm/oban/
• https://github.com/oliver-kriska/claude-elixir-phoenix (inspiration)
• https://elixirforum.com/