# 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](patterns/genserver.md) — Client/server separation, callbacks, state design
- [Error Handling](patterns/error-handling.md) — Error tuples, raise vs return, `with` chains
- [Data Transforms](patterns/data-transforms.md) — Pipelines, Enum/Stream idioms, reduce patterns
- [Process Design](patterns/process-design.md) — Supervision trees, process lifecycle, naming
- [Testing](patterns/testing.md) — ExUnit patterns, assertions, test organization
- [Documentation](patterns/documentation.md) — @moduledoc, @doc, @spec conventions
- [Typespecs](patterns/typespecs.md) — Type definitions, opaque types, when to use what
- [Macros](patterns/macros.md) — Macro patterns, hygiene, compile-time work
- [Behaviours](patterns/behaviours.md) — Behaviour design, callbacks, optional callbacks
- [Modules](patterns/modules.md) — Module organization, naming, structure

### Phoenix Patterns (`phoenix/`)
- [Phoenix Patterns](phoenix/patterns.md) — Endpoint, Router, Controller, Channel, PubSub
- [Phoenix Deviations](phoenix/deviations.md) — Where Phoenix differs from Elixir core

### Comparison (`comparison/`)
- [Elixir vs Phoenix](comparison/elixir-vs-phoenix.md) — Side-by-side comparison of approaches

### Code Smells (`smells/`)
- [Anti-Patterns](smells/anti-patterns.md) — Things the source avoids and why
- [Common Mistakes](smells/common-mistakes.md) — 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