01 / STARTING POINTS
Phoenix is our first choice for web applications. A CLI, library or device starts elsewhere.
Use Phoenix for routing, controllers and web application conventions. Add LiveView for server-driven interactive screens; an API-only product does not need a browser UI.
mix phx.new my_web_appChoose persistence from the product's needs. PostgreSQL + Ecto is our recommendation for shared relational web data, not a prerequisite for every Elixir program. Review generator options for API-only or database-free applications.
Keep command parsing separate from the modules that perform the work. OptionParser handles flags; the application owns help text, subcommands, output and exit codes.
mix new my_toolAn escript needs Erlang/OTP on the target machine. Evaluate Burrito when distributing a bundled executable to users without that runtime, and test each supported OS and architecture.
Define a small public module API, examples and tests. Generate documentation with ExDoc; publish to Hex if the package is intended for reuse outside the project. Add a supervision tree only if the library owns long-lived processes.
mix new my_libraryChoose supported Elixir/OTP versions and dependency constraints for consumers. A library does not need an HTTP server or database unless that is its purpose.
Use supervision for process lifecycles and recovery. Keep calculations and business operations in ordinary modules; introduce stateful processes where they are needed.
mix new my_service --supSupervision does not persist work. Choose durable storage or a queue when recovery requires it. Add Plug + Bandit for a small HTTP interface if needed; use Mix releases for deployment.
Use Livebook for interactive exploration, Explorer for tabular data, and Nx for numerical computation. Add Axon when defining or training neural networks is the requirement. Move reusable work into a Mix application when it needs a maintained API, tests or a service lifecycle.
Hosted model calls, local inference and training are different requirements. Check native backends, memory and hardware before selecting a deployment environment.
Start from the Nerves installation and project guides for the target hardware. Build firmware with the system and libraries that the device requires.
Hardware support, firmware updates and access to the device determine the setup. A web interface can be added when useful; it does not define the device application.
Build media pipelines with the source, processing and output elements needed for the product. Phoenix may provide a separate control interface if there is a web UI.
Protocols, codecs and native dependencies determine the pipeline and deployment. Ordinary file uploads do not require a media framework.
04 / OPTIONAL TOOLS
Choose these when the product needs them. Each entry explains the use case, how it fits, and the additional setup.
Login attempts, API calls, uploads or expensive actions need limits.
Define limits by actor, operation and time window; choose a backend that matches the deployment.
A node-local counter does not automatically enforce a cluster-wide quota. Choose the algorithm's burst behavior deliberately.
Features need gradual rollout, per-customer access or an operational off switch.
Choose an Ecto or Redis persistence adapter and configure synchronization between nodes.
Keep permission checks separate from rollout flags. Remove expired flags and restrict the management interface.
Uploads need to live in an S3 or compatible object store.
Use ExAws with its S3 service module for object operations and signed URLs. In a LiveView app, connect it to the upload flow.
The storage service, credentials, access rules and lifecycle policy are separate. Check which operations a compatible service actually supports.
The product needs thumbnails, resized uploads, image conversion or watermarks.
Process images through the libvips-backed Image API; use Oban for work that needs retries.
Vix/libvips introduces native runtime requirements. Check the deployment target and required codecs, and limit input dimensions and processing work.
The application needs CommonMark parsing, rendered Markdown content or transformations over a Markdown document tree.
Use MDEx to parse and transform a document or render HTML. Choose extensions and syntax highlighting deliberately; reserve HEEx components and expressions for trusted application-owned content.
Treat user-authored Markdown as untrusted input: configure and verify HTML sanitization, link handling and size limits. Never evaluate its HEEx expressions. MDEx uses native Rust code; verify precompiled artifact support or a Rust build toolchain for the deployment target.
Invoices, reports or other HTML documents need downloadable PDFs.
Render application-owned HTML and CSS through a managed Chrome process.
Chrome is an additional runtime dependency; PDF/A conversion also uses Ghostscript. Isolate rendering and control access to external resources.
Users need bulk uploads, data exports or integrations through CSV files.
Parse and write streams; validate each imported row through the application's business rules.
CSV parsing does not validate field types or business rules. Define malformed-row handling and spreadsheet formula escaping for exports.
External consumers need an OpenAPI contract for the Phoenix API.
Describe operations and schemas, validate requests, and test responses against the specification.
A schema does not enforce ownership or authorization. Keep the published contract aligned with application behavior.
Clients specifically need GraphQL queries, mutations or subscriptions.
Expose the existing business layer through a schema; use Dataloader where batching is needed.
Resolvers still need authorization and query-cost limits. Ordinary JSON endpoints remain simpler when GraphQL adds no client benefit.
Chat, collaborative screens or live rooms need connected-user state.
Track presence metadata and broadcast joins and leaves through Phoenix's existing realtime infrastructure.
Presence is ephemeral and eventually consistent. It is not a durable audit trail, access-control system or editing-conflict resolver.
The application needs interface copy in multiple languages.
Use the Gettext integration already present in typical Phoenix projects; maintain translation catalogs and plural forms.
It does not translate user-authored content automatically. Dates, amounts and units need locale-aware formatting too.
Dates, numbers, currencies and units must follow the user's locale.
Use CLDR-based formatting and parsing. For new projects, evaluate Localize as the documented successor to the ex_cldr family.
Existing ex_cldr applications need a planned migration. Check runtime requirements and package locale data for deployment.
Prices, invoices or balances need explicit currencies and decimal arithmetic.
Represent amount and currency together and make rounding rules explicit.
This is not payment processing, tax calculation or an accounting ledger. The package is ex_money; check its major-version migration notes.
The product needs text generation, streaming, structured outputs, embeddings or model tool calls through supported provider APIs.
Use a common Elixir interface to supported providers, including schema-constrained output and embedding generation. Keep provider-specific settings explicit; store embeddings separately when retrieval needs persistence.
Provider and model capabilities differ. Start here for direct model calls; add an agent framework only when orchestration needs it. Define application validation, permissions and representative evaluations separately.
A language model must select tools, keep agent state or run a bounded multistep reasoning loop.
Add Jido.AI to a Jido agent and use ReqLLM for provider access. Define tools as actions, and keep model selection, timeouts and tool policy explicit.
Model output is untrusted and nondeterministic. Restrict tool permissions and side effects, set cost and step limits, require approval for high-risk operations, and test representative tasks.
The main requirement is extracting typed fields from text into Ecto schemas, with casting, validation and retries.
Define an instruction with an Ecto schema and use changeset validation to check the returned fields. Choose this alternative when its Ecto integration fits better than ReqLLM structured output.
It is not an agent runtime and does not provide response streaming. Valid fields can still contain incorrect facts; handle failed validation, retry limits and domain checks explicitly.
The application is organized around message history, model responses and chained tool calls, or already uses the Elixir LangChain abstractions.
Compose messages, model adapters and tools through LLMChain. Use its callbacks for streaming and inspect tool-call trajectories when evaluating a conversation workflow.
This is an alternative orchestration approach, not an extra layer every ReqLLM or Jido application needs. Bound tool loops, authorize actions and implement persistence and retry behavior for the actual product.
An application already uses Ash resources and needs to expose selected actions as model tools or MCP tools, generate structured outputs or maintain embeddings.
Add Ash AI to the existing Ash domains and resources. Select the actions to expose and carry the authenticated actor and tenant into their execution; configure model access only for features that require it.
Choose Ash as an architecture first. Ash AI does not justify migrating an ordinary contexts application by itself. Test authorization for every exposed action and verify embedding updates, retrieval quality and model costs.
Embeddings are useful for semantic retrieval or recommendations alongside existing PostgreSQL data.
Enable the PostgreSQL vector extension and use the Elixir pgvector integration with Ecto or Postgrex.
The library does not generate embeddings. Verify database-extension support, dimensions, indexes and retrieval quality against representative queries.
Inference should run on infrastructure you control, using a supported pretrained model.
Load supported model architectures with Bumblebee and serve predictions through Nx.Serving.
Plan model memory, a suitable numerical backend and hardware. Model compatibility and licensing need to be checked individually.
The application consumes a stream from Kafka, RabbitMQ, SQS or another supported source.
Build concurrent processing stages with batching, acknowledgements and back-pressure.
The source connector determines delivery behavior. Keep handlers safe to retry; ordinary application jobs still fit Oban.
Imports, analytics or reports need dataframe transformations over CSV, Parquet or similar datasets.
Use typed series and dataframes for grouping, joining and transforming tabular data.
The default Polars backend uses native code. Check deployment support and memory use; routine application queries still belong in Ecto.
The project needs to define or train a neural network in Elixir rather than only run a supported pretrained model.
Use Axon to build models and training loops on Nx, with a numerical compiler/backend suited to the target hardware. Use Bumblebee when loading a supported pretrained model meets the requirement.
Check native backend support, hardware, memory and training data. Validate on held-out data and measure deployment behavior; adding Axon does not establish model quality or a performance advantage.
Producers and consumers need a custom event pipeline with demand-driven backpressure.
Model stages around runtime concurrency and data transfer; keep business steps in functions.
You own buffering, subscriptions and failure behavior. Use Task.async_stream for simpler bounded parallel work, or Broadway for its ingestion features.
A large enumerable needs parallel mapping, partitioned grouping, aggregation or windows.
Build a Flow pipeline and choose partition keys, stages and windows for the workload.
Coordination has overhead; small inputs can favor Enum or Task. Partitioning affects grouping and order; bound accumulating state.
A measured hot path has alternative implementations to compare.
Benchmark representative inputs with warmup, runtime, memory and reduction measurements.
Microbenchmarks do not establish application throughput or production latency. Check correctness and end-to-end behavior separately.
The application is slow and you need to locate expensive calls or repeated work.
Use the supported mix profile task or OTP profiler for the question; combine findings with the existing Telemetry events.
Check installed runtime support for tprof, eprof and fprof. Tracing can change timing and add overhead; profile a representative bounded workload.
A node-local cache needs expiration, eviction or fallback loading beyond a small ETS implementation.
Configure cache limits, expiration and loading behavior around the data lifecycle.
Define invalidation and stale-data policy. A local cache is not a durable source of truth or a cluster-wide consistency guarantee.
Profiling identifies CPU-heavy work suited to native code, or the product must call an existing Rust library.
Expose a narrow NIF interface and select normal versus dirty scheduling appropriate to the work.
Native faults can crash the VM. Validate target builds, scheduler impact and boundary-copying costs; consider a separate OS process when fault isolation is required.
Nx numerical work needs a compiled backend on supported CPU or accelerator hardware.
Use EXLA as the Nx compiler/backend and select the supported target, precision and memory settings.
Compilation, data transfer and native dependencies have costs. Verify hardware/toolchain support and measure representative workloads; it is not a general accelerator for arbitrary Elixir functions.
Bursty expensive work should run on additional ephemeral nodes, such as media processing or model inference.
Configure a bounded runner pool and an appropriate backend. Start only required application children and size runner database pools deliberately.
Boot latency, network transfer and capacity costs matter. FLAME supplies compute execution, not a durable job queue; pair it with Oban when jobs must persist.
Domains or layers need explicit, compiler-checked dependencies and public module exports. Useful for agent-maintained applications as well as human-maintained code.
Declare each boundary in its root module with use Boundary, explicit deps and a small exports list. Add the compile-time dependency and compiler below. A boundary always exports its root module; prefer explicit exports over exports: :all. Keep allowed calls aligned with the architecture.
Violations are compiler warnings unless compilation uses --warnings-as-errors. External OTP application calls are allowed by default; opt into selected app checks or strict mode when required. Dynamic calls such as apply/3 are not checked. Boundary enforces static module references; it does not isolate an agent’s files, processes or network access. Libraries can limit the compiler to dev/test as the compiler documentation describes.
# In mix.exs deps/0:
{:boundary, "~> 0.11", runtime: false}
# In mix.exs project/0:
compilers: [:boundary] ++ Mix.compilers()
# In each domain root module (adapt the names):
use Boundary, deps: [MyApp.Accounts], exports: []Run mix deps.get, then mix compile --warnings-as-errors in the environments your CI checks. Add a temporary forbidden static call to confirm the check fails, remove it, and rerun successfully. The dependency alone does not enforce boundaries.
A coding agent needs runtime context from a Phoenix application during development.
Add the Tidewave Phoenix integration as a development-only dependency and plug. Connect your coding agent to inspect logs, evaluate code, query the development database and read installed-version documentation.
This gives the agent access to the running development application. Use a trusted local environment and keep the dependency and endpoint out of production; this is tooling for building the app, not an AI feature for its users.
Resources, actions, policies and derived APIs form a substantial part of the application.
Evaluate Ash early as the domain layer beneath Phoenix, with only the extensions the product needs.
This changes how business logic is modeled. It is an architectural choice, not a small utility to install beside an unchanged contexts design.
The application needs cooperating agents that choose or coordinate steps, share reusable actions and react to routed signals.
Model the system with agents, actions, signals and directives, and run long-lived agents through Jido's supervised runtime. AI is optional; add Jido.AI only when decisions need a language model.
Prefer a plain GenServer, durable Oban jobs or an explicit function pipeline when behavior is fixed and simple. Supervision and in-memory state alone do not preserve progress across restarts; choose and verify persistence and resume behavior.
05 / THE THINKING
A command-line tool can start with Mix and OptionParser. A long-running service needs a supervision tree. A browser product benefits from Phoenix. These are different starting points within the same ecosystem.
Mix project typesFor web apps, use Phoenix, LiveView, contexts and Ecto as the foundation. Keep the generated HTTP server, asset pipeline and test setup.
Phoenix generator documentationContexts and Ecto are our default. Choose Ash when a resource-and-action model, policies and generated APIs fit the domain. It affects how the application is structured, so evaluate it before building out the data layer.
How Ash models an applicationOban needs database migrations and workers. Swoosh needs a delivery adapter. File uploads need storage and access rules. Every recommendation includes the remaining setup and the limits of the choice.
06 / FOR AGENTS
Read the existing project, choose an application path, and use the relevant reference. Do not install the whole menu.
First read https://elixir.menu/agents.md for direct Markdown and JSON retrieval. In the application, start with README.md, mix.exs, mix.lock and runtime pins. Preserve its architecture and follow its maintained workflow. Do not regenerate an existing project.
Identify the interface, whether work must keep running, persistence needs, and deployment target. Choose one of the starting points above; a product may combine more than one. Do not assume Phoenix or PostgreSQL.
Check elixir --version and mix --version. Follow the official Elixir installation guide if prerequisites are missing; respect existing version management. Install a web generator, database or specialist toolchain only for the selected path.
Use the selected starter and its current documentation. The commands above are scaffolding examples, not complete applications. For the Phoenix web path, follow setup.md; for Nerves and Membrane, follow their own project guides.
Read runtime.md for built-in state, concurrency and storage choices. Read optional.md and add only tools whose use cases match the product. Check versions, native dependencies and deployment constraints. Record the reasons and setup in the project’s maintained documentation. Preserve its existing agent-guidance conventions.
Run formatting, compilation and relevant tests. Exercise the real interface: CLI help, output and exit codes; service startup and recovery; HTTP behavior; or the target device. Verify the packaged artifact on the intended target and report what remains untested.
For a new web application with PostgreSQL. Check the current generator and supported runtime versions before running these steps.
Verified 6 October 2026 on macOS: Phoenix 1.8.15, LiveView 1.2.12, Elixir 1.20.4 / OTP 29.1.1 and PostgreSQL 18.3. Setup, auth migrations, formatting, compilation, 112 generated tests and four HTTP routes passed. Browser flows and production deployment remain untested.
Read the project README and runtime configuration if they exist. Confirm the operating system, intended app name and destination. Check the tools below; a missing command identifies a prerequisite to install. Do not generate into a directory containing unrelated work.
elixir --version
mix --version
mix phx.new --version
psql --versionCheck: Record the detected versions and missing tools. A PostgreSQL client version does not prove that a database server is running or accessible.
Use the official Elixir instructions for the detected operating system and a compatible Erlang/OTP version. Reuse the machine’s existing runtime manager. Install and start PostgreSQL using its operating-system-specific instructions. Linux development also needs inotify-tools for live reload. After Elixir is working, install missing Mix tooling and the Phoenix generator with the commands below. Respect any existing version pins; these unversioned commands are for a fresh setup.
mix local.hex
mix local.rebar
mix archive.install hex phx_newCheck: Record the selected versions in the project’s runtime configuration. Verify the application can connect to PostgreSQL using the intended local credentials before creating databases.
Replace my_app with the agreed application name. Keep Phoenix’s LiveView, mailer, asset and agent-guidance defaults. Respect the project’s established documentation conventions.
mix phx.new my_app --database postgres
cd my_appCheck: Configure the new application’s local database connection before running mix setup. Keep private credentials out of source control. Accept dependency installation when the generator prompts, or let mix setup fetch them.
Run this from the generated application directory, after configuring PostgreSQL. The generated setup task fetches dependencies, prepares the database and builds the development assets. Read its definition in mix.exs before using it in an existing application.
mix setupCheck: Setup must finish successfully. If a step fails, fix the reported prerequisite and resume from that step; do not regenerate over the application.
For first-party user accounts, generate Phoenix authentication with the LiveView option. Skip this step for an application without accounts. Follow any additional instructions printed by the generator.
mix phx.gen.auth Accounts User users --live
mix deps.get
mix ecto.migrateCheck: Review the generated account flows and authorization boundaries. Configure email delivery before relying on production magic links.
Format the generated code and any local configuration changes, then run the checks. Start the development server using the project’s normal process. Open the printed URL and verify the page loads. If accounts were generated, exercise registration and sign-in with development email.
mix format
mix format --check-formatted
mix compile --warnings-as-errors
mix test
mix phx.serverCheck: Report exact versions, the app location, startup URL, checks that passed and anything unverified. Keep README.md and mix.lock current. Do not describe the setup as production-ready or benchmarked.
Social login and OIDCAssent
Use it when
Users need to sign in with Google, GitHub, Apple or an OpenID Connect provider.
How it fits
Integrate provider authentication with the application's existing accounts and sessions.
What else to account for
Account linking, session management and permissions remain application concerns. SAML is a separate requirement.