Lesson 3: modules, structs & the shape of an Elixir project

How Elixir organizes code without classes

Primary source: Phoenix Contexts guide, which explains the architectural pattern behind how Speechwave is organized.

The mental model shift

In Ruby, organization revolves around classes. A Talk class holds both data (attributes) and behavior (methods). You call talk.save! and the object knows how to persist itself.

In Elixir, data and behavior are separated:

• Structs hold data (like a Ruby Struct: just fields, no methods)
• Modules hold functions that operate on that data

A %Talk{} struct doesn't know how to save itself. You pass it to Repo.insert/1, a function in a completely different module. Data flows through functions; it never "does" anything on its own.

Speechwave's architecture

Here's how your project maps this principle:

The pattern: Context modules (talks.ex, accounts.ex) sit next to directories of the same name containing the schemas they operate on. The context is the public API; the schemas are the data definitions.

Schemas: defining data shape

A schema maps a database table to an Elixir struct and defines how to validate changes.

lib/speechwave/talks/talk.ex

defmodule Speechwave.Talks.Talk do
  use Ecto.Schema
  import Ecto.Changeset

  schema "talks" do
    field :title, :string
    field :slug, :string

    has_many :talk_sessions, Speechwave.Talks.TalkSession
    belongs_to :user, Speechwave.Accounts.User

    timestamps(type: :utc_datetime)
  end

  def changeset(talk, attrs) do
    talk
    |> cast(attrs, [:title, :slug])
    |> validate_required([:title, :slug])
    |> validate_format(:slug, ~r/^[a-z0-9][a-z0-9-]*$/,
      message: "only lowercase letters, numbers, and hyphens"
    )
    |> validate_length(:slug, max: 100)
    |> unique_constraint(:slug)
  end
end

Let's break this down line by line:

The changeset function

Every schema has a changeset/2 function. It's the validation pipeline: it takes an existing struct and a map of new attributes, and returns a changeset describing the proposed changes with any validation errors attached.

def changeset(talk, attrs) do
  talk
  |> cast(attrs, [:title, :slug])        # pick allowed fields from attrs
  |> validate_required([:title, :slug])   # must be present
  |> validate_format(:slug, ~r/.../)      # must match regex
  |> validate_length(:slug, max: 100)     # max length
  |> unique_constraint(:slug)             # DB-level uniqueness
end

Functions like cast, validate_required, validate_format all come from Ecto.Changeset, available without a prefix because of the import Ecto.Changeset at the top.

class Talk < ApplicationRecord
  validates :title, :slug, presence: true
  validates :slug, format: { with: /\A[a-z0-9][a-z0-9-]*\z/ },
                   length: { maximum: 100 },
                   uniqueness: true
end

Plain structs (no database)

Not every struct maps to a database table. Scope is a plain struct: just defstruct, no schema.

lib/speechwave/accounts/scope.ex

defmodule Speechwave.Accounts.Scope do
  alias Speechwave.Accounts.User

  defstruct user: nil

  def for_user(%User{} = user) do
    %__MODULE__{user: user}
  end

  def for_user(nil), do: nil
end

Three things to notice:

• defstruct user: nil: defines a struct with one field (:user) defaulting to nil. No database table involved.
• %__MODULE__{user: user}: __MODULE__ is a compile-time constant that expands to the current module name. This is the same as writing %Speechwave.Accounts.Scope{user: user} but won't break if you rename the module.
• for_user/1 has two clauses: one for a real user (pattern matches %User{}), one for nil. This is the multi-clause pattern from Lesson 1.

The three import keywords

These appear at the top of almost every module and control which functions are available. They look similar but do very different things:

You can also multi-alias with braces:

lib/speechwave/accounts.ex:9

alias Speechwave.Accounts.{User, UserConsent, UserIdentity, UserNotifier, UserToken}

This creates five aliases in one line. Equivalent to writing five separate alias statements.

Contexts: the public API layer

Context modules are where behavior lives. They're the boundary between "what the app does" and "how data is shaped."

Compare the schema and context for Talks:

The context is what LiveViews and controllers call. They never reach into schemas for queries:

# LiveView calls the context
talks = Talks.list_talks(scope)

# NOT this (don't query from LiveViews):
talks = Repo.all(from t in Talk, where: ...)

How naming maps to files

Elixir has a simple convention: the module name maps to the file path.

Unlike Ruby, this is convention only. The compiler doesn't enforce it. But every Elixir project follows it, and your editor's "go to file" will work predictably.

Practice

import Ecto.Query
alias Speechwave.Talks.Talk

defmodule Speechwave.Accounts.User do
  use Ecto.Schema
  import Ecto.Changeset

  # ...
  def email_changeset(user, attrs, opts \\ []) do
    user
    |> cast(attrs, [:email])
    |> validate_required([:email])
    # ...
  end
end

Your next step

Open two files side by side:

• lib/speechwave/accounts/user.ex (the schema)
• lib/speechwave/accounts.ex (the context)

For each public function in accounts.ex, trace which schema it touches and how. Notice that the context never reaches into another context's schemas. Accounts works with User, UserToken, UserIdentity; Talks works with Talk and TalkSession. Each context owns its domain.