Idiomatic Elixir & Phoenix Patterns

Patterns, conventions, and code smells extracted directly from the Elixir and Phoenix source code — with citations to specific files and line numbers.

This is not opinion. This is what the source actually does.

Source Versions

• Elixir: main branch (cloned 2026-04-29)
• Phoenix: main branch (cloned 2026-04-29)

Structure

Core Patterns (patterns/)

• GenServer Patterns — Client/server separation, callbacks, state design
• Error Handling — Error tuples, raise vs return, with chains
• Data Transforms — Pipelines, Enum/Stream idioms, reduce patterns
• Process Design — Supervision trees, process lifecycle, naming
• Testing — ExUnit patterns, assertions, test organization
• Documentation — @moduledoc, @doc, @spec conventions
• Typespecs — Type definitions, opaque types, when to use what
• Macros — Macro patterns, hygiene, compile-time work
• Behaviours — Behaviour design, callbacks, optional callbacks
• Modules — Module organization, naming, structure

Phoenix Patterns (phoenix/)

• Phoenix Patterns — Endpoint, Router, Controller, Channel, PubSub
• Phoenix Deviations — Where Phoenix differs from Elixir core

Comparison (comparison/)

• Elixir vs Phoenix — Side-by-side comparison of approaches

Code Smells (smells/)

• Anti-Patterns — Things the source avoids and why
• Common Mistakes — What "bad Elixir" looks like

Philosophy

Every pattern here is backed by a source citation. If a pattern can't point to where the Elixir or Phoenix team actually does it, it doesn't belong here.

Contributing

Found a pattern worth adding? Open a PR with:

1. The pattern name
2. The exact file path and line range
3. Why it matters
4. What the anti-pattern looks like