Overview

Relevant source files

• CHANGELOG.md
• README.md
• documentation/tutorials/get-started.md
• lib/ash.ex
• lib/ash/resource.ex
• mix.exs
• mix.lock

Ash is a declarative, extensible framework for building Elixir applications. It provides a resource-oriented programming model where you define your application's data structures, business logic, and behaviors using a Domain-Specific Language (DSL), and Ash handles the execution, authorization, validation, and persistence concerns.

This page introduces the fundamental concepts and architecture of Ash. For step-by-step instructions on building your first Ash application, see Getting Started. For detailed information about specific subsystems, see the child pages under this Overview section.

Core Philosophy

Ash operates on the principle of declarative resource definitions. Rather than writing imperative code for CRUD operations, you declare:

• What your data looks like (Ash.Resource with attributes)
• What operations can be performed (actions)
• How data relates to other data (relationships)
• Who can do what (Ash.Policy.Authorizer)
• Where data is stored (data layers like Ash.DataLayer.Ets, AshPostgres, etc.)

The framework then provides a consistent interface for working with these resources through modules like Ash, Ash.Query, and Ash.Changeset.

Sources: mix.exs9-11 README.md1-22 lib/ash.ex1-8

Fundamental Building Blocks

Diagram: Ash Framework Component Relationships

The framework consists of three primary layers:

1. Definition Layer: Ash.Resource modules define data structures, actions, and behaviors
2. Execution Layer: Ash.Changeset, Ash.Query, and Ash.ActionInput structures prepare operations; the Ash module executes them
3. Storage Layer: Ash.DataLayer implementations handle persistence

Sources: lib/ash/resource.ex5-10 lib/ash.ex5-8 documentation/tutorials/get-started.md106-153

Resources and Domains

Resources

A resource is a module that uses Ash.Resource and defines a data entity. Resources declare:

• Attributes: Fields that hold data (defined in the attributes DSL block)
• Relationships: Connections to other resources (belongs_to, has_many, etc.)
• Actions: Operations that can be performed (create, read, update, destroy, action)
• Calculations: Computed values derived from other fields
• Aggregates: Summarized data from related resources
• Validations: Rules to ensure data integrity

Sources: lib/ash/resource.ex1-24 documentation/tutorials/get-started.md119-179

Domains

A domain is a module that uses Ash.Domain and groups related resources together. Domains serve as the entry point for interacting with resources and define which resources are available in a given context.

Domains must be registered in your application configuration:

Sources: documentation/tutorials/get-started.md145-153 documentation/tutorials/get-started.md196-200 lib/ash/resource.ex72-117

Action Execution Model

Diagram: Action Execution Flow with Code Entities

Actions in Ash follow a consistent pattern:

1. Preparation: Create an Ash.Changeset (for mutations), Ash.Query (for reads), or Ash.ActionInput (for generic actions)
2. Execution: Pass the prepared structure to the appropriate Ash module function
3. Result: Receive the result (records, bulk results, or custom return values)

Example:

Sources: documentation/tutorials/get-started.md206-223 documentation/tutorials/get-started.md281-300 lib/ash.ex1-8

Type System

Ash includes a comprehensive type system for attributes and arguments. All types implement the Ash.Type behavior.

Category	Examples	Module Path
Primitives	:string, :integer, :boolean, :float, :atom	Ash.Type.*
Temporal	:date, :datetime, :time, :duration	Ash.Type.Date, etc.
Special	:uuid, :map, :term	Ash.Type.UUID, etc.
Collections	{:array, type}	Ash.Type with constraints
Custom	Embedded resources, unions, newtypes	Ash.Resource, Ash.Type.Union

Types define how values are:

• Cast from external input (cast_input/3)
• Validated with constraints (apply_constraints/2)
• Stored in the data layer (dump_to_native/2)
• Loaded from the data layer (cast_stored/2)

Sources: lib/ash/resource.ex1-24 mix.exs references to type modules

Extension System

Ash's extension system allows you to add functionality to resources through extensions. Extensions use the Spark DSL framework to add new configuration options.

Core Extensions

Diagram: Extension Architecture

Data Layers implement the Ash.DataLayer behavior and handle persistence:

• Ash.DataLayer.Ets - In-memory storage using Erlang Term Storage
• Ash.DataLayer.Mnesia - Distributed in-memory storage
• Ash.DataLayer.Simple - No persistence (for testing/static data)
• AshPostgres.DataLayer, AshSqlite.DataLayer - External packages for databases

Authorizers implement the Ash.Authorizer behavior and control access:

• Ash.Policy.Authorizer - Declarative policy-based authorization using a SAT solver

Notifiers implement the Ash.Notifier behavior and react to changes:

• Ash.Notifier.PubSub - Phoenix.PubSub integration for broadcasting events

Sources: lib/ash/resource.ex15-29 mix.exs56-63 README.md142-148

Query and Filter System

The Ash.Query module provides a fluent interface for building queries with filters, sorts, and data loading.

Diagram: Query Building API

Example queries:

Filters are parsed into expression trees (see Ash.Filter) that can be:

• Executed natively by the data layer (most efficient)
• Evaluated in-memory using Ash.Filter.Runtime (fallback)

Sources: documentation/tutorials/get-started.md423-460 lib/ash.ex88-151

Code Interface Generation

Resources can generate code interfaces for ergonomic access. This is done through the code_interface DSL section:

This generates functions like:

• MyApp.Ticket.open!(subject)
• MyApp.Ticket.close!(ticket)
• MyApp.Ticket.list!()

Sources: lib/ash/resource.ex294-304 README.md89 documentation/tutorials/get-started.md666-669

Working Example

Here's a minimal working example showing the core concepts:

Sources: documentation/tutorials/get-started.md119-300

Key Architectural Principles

1. Declarative over Imperative: Define what your system does, not how
2. Single Source of Truth: Resource definitions are the canonical specification
3. Separation of Concerns: Business logic, authorization, and persistence are separate
4. Composability: Extensions and behaviors compose without coupling
5. Runtime Safety: Compile-time validation where possible, clear errors at runtime

Next Steps

• Key Concepts - Detailed explanation of fundamental Ash concepts
• Architecture Overview - Deep dive into the framework architecture
• Getting Started - Build your first Ash application
• Resources - Complete resource system documentation
• Query System - Advanced querying and filtering
• Authorization - Policy-based access control

Sources: README.md23-122 documentation/tutorials/get-started.md1-670 mix.exs1-449