docs: idiomatic Elixir and Phoenix patterns with source citations

Extracted patterns, conventions, and code smells directly from the Elixir and Phoenix source code with file path and line number citations. Covers: GenServer, error handling, data transforms, process design, testing, documentation, typespecs, macros, behaviours, module organization, Phoenix-specific patterns, framework deviations, and anti-patterns.
2026-04-29 22:50:12 -07:00
commit 4ea9a884aa
16 changed files with 4857 additions and 0 deletions
@@ -0,0 +1,47 @@
+# 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