Elixir Phoenix Best Practices: Essential Coding Rules for Scalable Web Apps

Elevate your Elixir and Phoenix projects with these refined coding standards, inspired by pragmatic functional programming principles. Prioritize the newest versions of all dependencies, including Phoenix, for security and features.

### Key Philosophical Foundations
- **Business Domain Focus**: Structure your codebase around core business areas rather than tech stacks
- **Pure Logic Isolation**: Keep domain functions pure, isolating side effects to outer layers
- **Clarity Priority**: Choose explicit code over clever shortcuts
- **Composable Modules**: Favor small, combinable parts instead of deep inheritance
- **Focused Responsibilities**: Limit each function and module to a single, clear purpose
- **Adaptable Architecture**: Build for easy evolution and updates
- **Early Error Detection**: Catch issues immediately and recover gracefully
- **Minimal Features**: Implement only what's immediately required (YAGNI)

### Recommended Project Layout
- **Domain Contexts**: Leverage Phoenix contexts to separate business areas
  - `lib/my_app/`
    - `accounts/` for authentication and profiles
    - `billing/` for transactions
    - `catalog/` for inventory management
- **API vs. Impl Split**: Expose clean APIs that forward to private impl modules
  - Example: `defdelegate create_user(params), to: UserHandler`
- **Input Guards**: Employ NimbleOptions for strict boundary validation

### Effective Coding Techniques
- **Pattern Matching Control**: Drive logic with function head matches
- **Error Chaining**: Apply `with` for sequential, fail-safe operations
  - `with {:ok, user} <- fetch_user(id), {:ok, data} <- modify_user(user, params) do ... end`
- **Type Annotations**: Specify `@spec` for all exported functions
  - `@spec create_user(map()) :: {:ok, User.t()} | {:error, Ecto.Changeset.t()}`
- **Immutable Updates**: Always produce fresh data copies
- **Boundary Checks**: Use Ecto.Changesets for validation beyond DB ops
  - Chain `cast/3`, `validate_required/2`, `validate_format/3`
- **Success/Error Tags**: Standardize on `{:ok, value}` or `{:error, msg}` returns

### Robust Process Management
- **Stateful GenServers**: Handle mutable state via GenServer callbacks
- **Tree Supervision**: Craft fault-tolerant supervisor strategies
- **Dynamic Registries**: Registry for name-based process discovery
- **Async Tasks**: Task.Supervisor for parallel, crash-safe jobs
- **Independent Failures**: Isolate processes to prevent cascade crashes
- **Crash Recovery**: Rely on supervisors for automatic restarts

### Phoenix-Specific Optimizations
- **LiveView Priority**: Default to LiveView for interactive UIs
- **Reusable Functions**: Craft UI as pure function components
- **Real-Time PubSub**: Phoenix.PubSub for live updates
- **Context Respect**: Controllers/LiveViews delegate to contexts
- **Slim Controllers**: Offload logic from controllers
- **Security Checks**: Guard against CSRF, XSS in every endpoint

### Comprehensive Testing Approach
- **API-Centric Tests**: Target public context interfaces
- **Mocking with Mox**: Simulate external services
- **Property Tests**: StreamData for edge-case generation
- **Data Builders**: ExMachina for fixtures
- **Doc-Like Tests**: Make tests self-explanatory
- **AAA Pattern**: Setup → Execute → Verify structure

### External Integration Rules
- **Modern HTTP**: Req library over legacy clients
- **Behavior Contracts**: Define protocols for mockable clients
- **Resilient Errors**: Graceful handling of timeouts/network issues
- **Timeout Enforcement**: Set limits on all outbound calls
- **Breaker Patterns**: Circuit breakers for flaky services

### Naming and Style Standards
- **Snake_case Vars/Funcs**: `build_profile/1`
- **Action-Led Names**: Verbs first, e.g., `fetch_orders/1`
- **Collection Plurals**: `list_users/0`
- **Uniform Vocab**: Consistent domain terms
- **Intent-Focused**: Names explain purpose clearly

### Docs, Quality, and Perf
- **@doc Mandates**: Document all public APIs with examples
- **Analysis Tools**: Credo/Dialyzer for checks
- **Auto-Format**: `mix format` everywhere
- **Ongoing Refactors**: Improve without behavior shifts
- **Sparse Comments**: Explain rationale, skip obvious
- **Query Efficiency**: Preload/join to beat N+1
- **Smart Paging/Jobs**: Paginate + Oban for heavy lifts
- **Profile-Driven**: Measure before tweaks, cache wisely