# Elixir — Comprehensive Development Guide

## Quick Reference

| Item | Value |
|------|-------|
| Current Version | **Elixir 1.19.5** (target for all new code) |
| Required OTP | **OTP 27+** (OTP 28 supported) |
| Phoenix Version | **1.8.5** (latest — requires `:formats` on controllers) |
| Cortex Status | Elixir **not yet installed** on cortex.hydrascale.net |
| AI Agent Tooling | `usage_rules` hex package (~> 1.2) — **always include** |
| Production Framework | **Ash Framework** for substantial projects |
| Agent Framework | **Jido** (~> 2.1) for multi-agent systems |
| Paradigm | Functional, concurrent, fault-tolerant on BEAM VM |

---

## CRITICAL RULES — Read First

1. **Target Elixir 1.19.5** — not 1.15, not 1.17. Use current idioms and features.
2. **Always add `usage_rules`** to every project: `{:usage_rules, "~> 1.1", only: [:dev]}`.
3. **Use Ash Framework** for production/substantial projects (not necessarily POCs).
4. **Cortex is Elixir-first** — Elixir is the primary orchestrator, with interop to Python/Rust/Zig.
5. **Never use deprecated patterns** from pre-1.16 code (see Part 1).
6. **Phoenix 1.8** — always specify `:formats` on controllers, use `~p` verified routes, use scopes.
7. **For agentic workflows** — consider `GenStateMachine` over GenServer (built-in timeouts, state enter, postpone). For multi-agent orchestration, use **Jido**.

---

## Guide Structure — Load What You Need

This guide is split into focused parts. Load the part relevant to your current task:

### Part 1: Core Language & OTP (`elixir-part1-core.md`)
Elixir 1.19 features, type system, breaking changes since 1.15, pattern matching, pipelines, with expressions, structs, protocols, behaviours, Mix project structure, testing.

### Part 2: Concurrency & OTP (`elixir-part2-concurrency.md`)
BEAM processes, message passing, GenServer, Supervisors, DynamicSupervisor, Task, GenStateMachine (state machines for agentic workflows), Registry, ETS.

### Part 3: Phoenix Framework (`elixir-part3-phoenix.md`)
Phoenix 1.8.5 — router/pipelines, verified routes, controllers, HEEx components, LiveView, Channels, contexts, Ecto, authentication, scopes, telemetry, security, testing, generators, deployment.

### Part 4: Ecosystem & Production (`elixir-part4-ecosystem.md`)
Ash Framework, Jido (multi-agent systems), usage_rules, OTP releases, Docker deployment, distributed Erlang, monitoring (PromEx/Prometheus/Grafana), CI/CD, interop (Python/Rust/Zig), common libraries, cortex deployment plan, anti-patterns.

---

## Common Libraries Quick Reference

| Library | Purpose | Hex |
|---------|---------|-----|
| Phoenix | Web framework + LiveView | `{:phoenix, "~> 1.8"}` |
| Ecto | Database wrapper + query DSL | `{:ecto_sql, "~> 3.12"}` |
| Ash | Declarative resource framework | `{:ash, "~> 3.0"}` |
| Jido | Multi-agent orchestration | `{:jido, "~> 2.1"}` |
| GenStateMachine | State machines (wraps gen_statem) | `{:gen_state_machine, "~> 3.0"}` |
| Oban | Background job processing | `{:oban, "~> 2.18"}` |
| Req | HTTP client (modern) | `{:req, "~> 0.5"}` |
| Jason | JSON encoding/decoding | `{:jason, "~> 1.4"}` |
| Swoosh | Email sending | `{:swoosh, "~> 1.16"}` |
| Mox | Mock behaviours for testing | `{:mox, "~> 1.1", only: :test}` |
| Credo | Static analysis / linting | `{:credo, "~> 1.7", only: [:dev, :test]}` |
| libcluster | Automatic BEAM node clustering | `{:libcluster, "~> 3.4"}` |
| Horde | Distributed supervisor/registry | `{:horde, "~> 0.9"}` |
| Nx | Numerical computing / tensors | `{:nx, "~> 0.9"}` |
| Broadway | Data ingestion pipelines | `{:broadway, "~> 1.1"}` |
| PromEx | Prometheus metrics for Elixir | `{:prom_ex, "~> 1.9"}` |
| usage_rules | AI agent docs from deps | `{:usage_rules, "~> 1.1", only: :dev}` |