It’s also where the has_many :services association from episode 1’s domain sketch finally gets written into the User model. It’s been sitting in a blog post as a design decision for two episodes; today it becomes real code.

This is a long one on purpose — the goal is that nothing in the diff is left unexplained: every generated file, every line we added by hand, every option passed to every method.

Code is tagged episode-3 in the vicinote-tutorial repo.

What this episode touches, at a glance

Before going file by file, here’s the map. Two new models, one changed model, one new controller, two new views, a routing change, a seed file, and a one-line translation fix:

db/migrate/..._create_categories.rb   new  — the categories table
db/migrate/..._create_services.rb     new  — the services table
app/models/category.rb                new  — Category: has_many :services, validates :name
app/models/service.rb                 new  — Service: belongs_to :user/:category, validations, price accessor
app/models/user.rb                    edit — adds has_many :services
app/controllers/services_controller.rb new — index (public), new, create (both signed-in only)
app/views/services/index.html.erb     new  — the listing page
app/views/services/new.html.erb       new  — the "offer a service" form
config/routes.rb                      edit — resources :services, only: [:index, :new, :create]
config/locales/en.yml                 edit — fixes a leaked internal attribute name in error messages, sets the default currency to euros
db/seeds.rb                           edit — the fixed list of categories
app/views/pages/home.html.erb         edit — the two placeholder buttons now link somewhere

Generating the two models

bin/rails generate model Category "name:string:uniq"
bin/rails generate model Service title:string description:text price_cents:integer user:references category:references

Every field:type pair after the model name becomes a migration column. The syntax has a few extra tricks worth spelling out, since both commands use them:

• name:string:uniq — the third segment, :uniq, isn’t a type. It tells the generator to also add a unique index on that column, so it writes an add_index call for us instead of us remembering to add one later.
• user:references and category:references — references isn’t a column type either, it’s a generator shorthand meaning “this model belongs to that one.” It expands into a t.references call in the migration (a foreign-key integer column plus an index), and it makes the generator write a belongs_to :user / belongs_to :category line directly into the generated model file. That’s why Service’s model already has both associations in it the moment the generator finishes — we didn’t type belongs_to ourselves.

Each command prints what it created:

      create    db/migrate/20260820055929_create_categories.rb
      create    app/models/category.rb
      invoke    test_unit
      create      test/models/category_test.rb
      create      test/fixtures/categories.yml

      create    db/migrate/20260820055946_create_services.rb
      create    app/models/service.rb
      invoke    test_unit
      create      test/models/service_test.rb
      create      test/fixtures/services.yml

The test_unit files are Rails’ default test scaffolding (an empty test class and an empty fixture file) — this series isn’t using them, so they’re left as generated and not discussed further.

The categories migration, line by line

Generated, then hand-edited to add one word:

# db/migrate/..._create_categories.rb
class CreateCategories < ActiveRecord::Migration[8.1]
  def change
    create_table :categories do |t|
      t.string :name, null: false

      t.timestamps
    end
    add_index :categories, :name, unique: true
  end
end

• class CreateCategories < ActiveRecord::Migration[8.1] — every migration is a subclass of ActiveRecord::Migration, versioned to the Rails release that generated it ([8.1]). That version pin is what lets Rails change migration DSL behavior across major versions without silently breaking migrations written for an older one.
• def change — the one method Rails needs. For operations it can reverse automatically (creating a table, adding a column, adding an index), change is enough; Rails infers how to undo it if you ever roll the migration back. Irreversible operations would need separate up/down methods instead — nothing here needs that.
• create_table :categories do |t| — opens the table definition block; t is the object every column gets defined on.
• t.string :name, null: false — a VARCHAR column. The generator wrote t.string :name; the null: false is the one word we added by hand, matching the same rigor episode 2 put into the users table. Without it, Postgres would happily store a category with no name at all, and that’s not a state the app has any use for.
• t.timestamps — shorthand for two columns, created_at and updated_at, both datetime, both filled in automatically by ActiveRecord on create/update. Almost every table in this series has this line; Category is no exception.
• add_index :categories, :name, unique: true — this is what :uniq in the generator command produced. It’s a database-level uniqueness guarantee, enforced by Postgres itself, not just by a Rails validation that could in theory be bypassed by two simultaneous requests racing each other. Category also validates uniqueness in the model (below) — belt and suspenders: the model validation gives a friendly error in the normal case, the index guarantees correctness even under a race.

The services migration, line by line

# db/migrate/..._create_services.rb
class CreateServices < ActiveRecord::Migration[8.1]
  def change
    create_table :services do |t|
      t.string :title, null: false
      t.text :description, null: false
      t.integer :price_cents, null: false
      t.references :user, null: false, foreign_key: true
      t.references :category, null: false, foreign_key: true

      t.timestamps
    end
  end
end

• t.string :title, null: false — same shape as Category#name: a required short text field.
• t.text :description, null: false — text instead of string. In Postgres this is really a formality (both map to the same unbounded text type under the hood; Rails’ string vs text distinction is mostly a Rails-level hint, not a Postgres storage difference), but it signals intent: this column holds a paragraph, not a label, and some form helpers (form.text_area instead of form.text_field) key off exactly this type later.
• t.integer :price_cents, null: false — a plain integer. There’s a whole section below on why this is an integer and not a decimal.
• t.references :user, null: false, foreign_key: true — this line is what user:references on the command line generated, and it’s doing three things at once:
  1. Adding an integer column named user_id (the _id suffix and the pluralization-to-singular are both Rails convention, not something we typed).
  2. foreign_key: true — adds an actual Postgres foreign key constraint from services.user_id to users.id. The database itself will now refuse to insert a Service row whose user_id doesn’t match a real user, and refuses to delete a User row that still has services pointing at it (unless the association says otherwise — more on that below).
  3. An index on user_id, added automatically, because a foreign-key column that isn’t indexed makes every query that joins through it slow as the table grows. This one wasn’t optional or something we asked for — t.references always indexes. null: false here means every service must belong to somebody; there’s no such thing as a service with no provider.
• t.references :category, null: false, foreign_key: true — identical shape, for the other side of the relationship.

Notice neither migration says anything about belongs_to or has_many — migrations only describe the database schema (tables, columns, constraints, indexes). Associations are a separate, Ruby-level concept declared in the models, which is the next section.

Running the migrations

bin/rails db:migrate

This runs both pending migrations in timestamp order (categories, then services — services’ foreign key to categories needs the categories table to already exist) and rewrites db/schema.rb to reflect the new state. schema.rb isn’t something to edit by hand; it’s Rails’ cached snapshot of “what the database currently looks like,” regenerated every time you migrate, and it’s what a teammate’s bin/rails db:setup reads to build a fresh database that matches yours without replaying every migration ever written.

The generated models, before any edits

Right after the generator ran, before we touched anything:

# app/models/category.rb
class Category < ApplicationRecord
end

# app/models/service.rb
class Service < ApplicationRecord
  belongs_to :user
  belongs_to :category
end

Category is empty because it has no references columns — there was nothing for the generator to infer an association from. Service already has both belongs_to lines because of the :references fields we passed on the command line, as explained above. Both inherit from ApplicationRecord, the abstract base class every model in a Rails app shares (itself a thin subclass of ActiveRecord::Base), which is what gives them .find, .create, .where, validations, and everything else ActiveRecord provides — none of that is written in either file, it’s inherited.

One thing worth naming explicitly: as of Rails 5, belongs_to is required by default. Writing belongs_to :user doesn’t just declare the association, it also implicitly adds a presence validation — a Service without a user fails validation, on top of the database already refusing it via the null: false, foreign_key: true from the migration. Two independent layers enforcing the same rule, at two different levels (Ruby validation vs. SQL constraint), which is exactly the “Category must exist” error message you’ll see later in this post — that sentence is Rails’ default wording for a failed belongs_to presence check on category.

Category, filled in

# app/models/category.rb
class Category < ApplicationRecord
  has_many :services

  validates :name, presence: true, uniqueness: true
end

• has_many :services — the other half of Service belongs_to :category. Rails associations are declared on both ends by hand; there’s no way to declare just one side and have the other inferred. This is what makes some_category.services work — the association looks up every Service row whose category_id matches, via the foreign key the migration created.
• validates :name, presence: true, uniqueness: true — presence: true duplicates what the null: false in the migration already guarantees at the database level, but for a different audience: a failed database constraint raises an ugly ActiveRecord::NotNullViolation exception, while a failed presence validation gives @category.errors a friendly message a view can render. uniqueness: true is the model-level half of the belt-and-suspenders pair with the migration’s unique index — this one runs a SELECT before saving and gives a clean error; the index is what actually stops a duplicate from ever reaching the table if two requests race each other past the validation at the same instant.

Service, filled in

# app/models/service.rb
class Service < ApplicationRecord
  belongs_to :user
  belongs_to :category

  validates :title, presence: true
  validates :description, presence: true
  validates :price_cents, presence: true, numericality: { greater_than: 0, only_integer: true }

  # price_cents is what's stored and compared (no float rounding surprises),
  # but nobody wants to type cents into a form. This speaks euros on the
  # way in and out, so the form field can just be "price".
  def price
    price_cents && price_cents / 100.0
  end

  def price=(value)
    self.price_cents = value.present? ? (value.to_f * 100).round : nil
  end
end

• validates :title, presence: true / validates :description, presence: true — same reasoning as Category#name: the migration’s null: false is the last line of defense, this is the friendly one that runs first.
• validates :price_cents, presence: true, numericality: { greater_than: 0, only_integer: true } — three checks bundled into one line. presence: true rejects nil. numericality: on its own would just reject anything that isn’t a number at all (a string like "abc"); the greater_than: 0 option adds the business rule that a free service isn’t a thing this validation allows, and only_integer: true rejects fractional cents (4250.5), which shouldn’t be reachable anyway since price_cents is a database integer column, but the validation makes the rule explicit rather than relying on the column type alone to enforce it before the value ever reaches the database.
• def price / def price= — covered in full in the next section; this is the piece that lets a form talk in euros while the column underneath stays cents.

A decision worth slowing down on: price_cents, not price

The generator wrote price_cents:integer, not price:decimal, on the command line — that phrasing was chosen deliberately going in, and it’s the same category of decision episode 1 made about Booking storing its own price rather than reading service.price live: money handled as a float, or even a naive decimal, eventually produces a rounding error that shows up as a few cents off on an invoice, at the worst possible moment. Storing the amount as an integer number of cents sidesteps the whole class of bug — there’s no fractional part to round, because there’s no fraction at all. €42.50 is stored as the integer 4250, full stop. Naming it price_cents rather than, say, price_usd_cents is deliberate too — “cents” is the minor unit of euros just as much as it is of dollars, so nothing about the column itself is tied to a currency; only the formatting layer, covered later in this post, has any idea which one is in use.

The cost is that nobody wants to type “4250” into a form and mean €42.50. So Service gets a small virtual accessor — two plain Ruby methods, not a database column — that translates euros to cents and back:

def price
  price_cents && price_cents / 100.0
end

def price=(value)
  self.price_cents = value.present? ? (value.to_f * 100).round : nil
end

Walking through both:

• def price — reads for display. price_cents && price_cents / 100.0 uses Ruby’s && for its short-circuit behavior, not as a boolean check: if price_cents is nil (a brand-new, unsaved Service), the whole expression short-circuits to nil without attempting nil / 100.0, which would raise. If it’s a real integer, && evaluates and returns the right-hand side — the division. Dividing by 100.0 (a float literal, not 100) forces Ruby to do floating-point division rather than integer division, so 4250 / 100.0 gives 42.5, not 42 truncated.
• def price=(value) — the setter, called automatically whenever something does service.price = "42.50" or, just as automatically, whenever a form submits a field named price through mass assignment (Service.new(price: "42.50", ...)) — Rails calls the setter method for every permitted attribute, it doesn’t care whether that method backs a real column or not. value.present? guards against blank input (an empty string from a cleared form field) rather than trying to convert "" into a number. When there is a value, value.to_f * 100 converts to euros-as-a-float and multiplies by 100 to get cents, and .round turns that back into a whole number — .to_f on user input can produce things like 42.499999999999996 due to ordinary floating-point imprecision, and .round is what cleans that back up to exactly 4250 before it ever reaches price_cents=.

Because price= is a normal Ruby method and not an ActiveRecord-backed attribute, it runs immediately when attributes are assigned — before save, before any validation. By the time validates :price_cents, ... runs, price_cents has already been populated by this setter. The form field discussed later in this post is just form.text_field :price — the view never has any idea cents exist.

Categories are seeded, not created

A marketplace where anyone can invent a new category ends up with fifty categories that mean the same thing, spelled five different ways, and browsing-by-category stops being useful. VicinoTe curates a fixed list instead, in db/seeds.rb:

# db/seeds.rb
[
  "Home Repair",
  "Tutoring",
  "Cleaning",
  "Gardening",
  "Pet Care",
  "Moving Help",
  "Tech Support",
  "Beauty & Wellness"
].each do |name|
  Category.find_or_create_by!(name: name)
end

• The literal array of eight strings is the list of categories, in plain Ruby, right there in the seed file — no admin UI, no separate config format, just a source-controlled array a future episode could extend by adding a ninth string.
• .each do |name| ... end iterates the array once per category.
• Category.find_or_create_by!(name: name) — this single method does two jobs depending on what it finds: if a Category with that name already exists, it returns it untouched; if not, it builds and saves a new one. The trailing ! means it raises ActiveRecord::RecordInvalid on a validation failure instead of silently returning an unsaved, invalid record — which matters here, because a seed file failing loudly is much easier to debug than one that fails quietly and leaves the database half-seeded.

That combination — a fixed array plus find_or_create_by! — is what makes the file safe to run more than once. Running db:seed again after adding a ninth category to the array later creates only the new one; the first eight are matched by name and left alone, not duplicated.

bin/rails db:migrate
bin/rails db:seed

db:seed just executes db/seeds.rb as a plain Ruby script inside the app’s environment — nothing more mysterious than that.

Writing the association episode 1 only sketched

Episode 1’s domain design showed this code as an illustration of the “role emerges from the association” decision — the whole point being that a User isn’t tagged with a role: "provider" column, it’s a provider because it has services. It was never actually in the User model, though; episode 2 was about authentication and didn’t touch it. It goes in now:

# app/models/user.rb
class User < ApplicationRecord
  has_secure_password
  has_many :sessions, dependent: :destroy
  has_many :services, dependent: :destroy

  normalizes :email_address, with: ->(e) { e.strip.downcase }
end

Only one line changed — has_many :services, dependent: :destroy was added, everything else (has_secure_password, the sessions association, the email normalization) is untouched from episode 2.

dependent: :destroy matches what sessions already does on the line above it, for the same reason: without it, deleting a User would either fail outright (the database’s foreign_key: true constraint from the migration would reject the delete, since services rows would still point at a user_id that’s about to stop existing) or, if the constraint were relaxed, leave orphaned Service rows in the table forever, pointing at nobody. dependent: :destroy tells Rails to delete every associated Service first, automatically, whenever a User is destroyed — the cleanup is one word, not something every future call site has to remember to do by hand.

The controller: public index, protected everything else

# app/controllers/services_controller.rb
class ServicesController < ApplicationController
  allow_unauthenticated_access only: :index

  def index
    @services = Service.includes(:category, :user).order(created_at: :desc)
  end

  def new
    @service = Current.user.services.new
  end

  def create
    @service = Current.user.services.new(service_params)

    if @service.save
      redirect_to services_path, notice: "Your service is live."
    else
      render :new, status: :unprocessable_entity
    end
  end

  private

  def service_params
    params.require(:service).permit(:title, :description, :price, :category_id)
  end
end

Line by line:

• class ServicesController < ApplicationController — every controller in a Rails app inherits from ApplicationController, which is where episode 2’s Authentication concern is included. That’s what makes the next line meaningful.
• allow_unauthenticated_access only: :index — episode 2’s Authentication concern runs before_action :require_authentication for every action on every controller by default, which means without this line, an anonymous visitor hitting any action here would be redirected straight to the sign-in page. That’s correct for new and create — nobody should be able to list a service anonymously — but wrong for index: browsing the marketplace has to work for someone who hasn’t signed up yet, or there’s no reason to sign up in the first place. only: :index opts that one action back out of the requirement while leaving new and create protected. This is the exact same mechanism episode 2 used, with no argument at all (allow_unauthenticated_access, no only:), to make the entire PagesController public — here we only want one of three actions exempted, so only: narrows it.
• def index / @services = Service.includes(:category, :user).order(created_at: :desc) — Service.includes(:category, :user) isn’t filtering anything; includes is ActiveRecord’s eager-loading method. Without it, a view that loops over @services and calls service.category.name and service.user.email_address for each one would fire one additional SELECT per service, per association — the classic N+1 query problem, where displaying 50 services silently means 101 queries (1 for the list, plus 50 for categories, plus 50 for users) instead of 3. includes loads the categories and users for every service up front, in a small fixed number of extra queries, regardless of how many services there are. .order(created_at: :desc) sorts newest-first, so a new listing shows up at the top of the page rather than the bottom.
• def new / @service = Current.user.services.new — this is the payoff of wiring has_many :services onto User a section ago. Current.user is the currently authenticated user (from episode 2’s Current model, an ActiveSupport::CurrentAttributes subclass). Calling .services.new through the association, rather than Service.new on its own, pre-fills the new record’s user_id with Current.user.id automatically — the instance this line builds already knows who it belongs to before a single form field has been filled in.
• def create — Current.user.services.new(service_params) does the same association-scoped build as new, but this time passing in the submitted form data as well. Because the user side of the association is set by Current.user.services, not by anything in service_params, there’s no user_id field anywhere in the permitted params below for a malicious visitor to tamper with and claim a listing on someone else’s behalf — the provider is whoever Current.user says it is, full stop, not whatever a hidden form field might claim.
• if @service.save — save runs validations and, if they all pass, performs the INSERT and returns true; if any validation fails, it does nothing to the database and returns false — no exception raised, which is why this is a plain if, not a begin/rescue.
• redirect_to services_path, notice: "Your service is live." — on success, a real HTTP redirect to the index (this is the same Post/Redirect/Get pattern episode 3 of ai-with-ruby discusses in more depth: redirecting after a state-changing POST means refreshing the result page never re-submits the form). notice: stores a one-time message in the flash — it survives exactly one redirect and then clears itself, which is how “Your service is live.” shows up on the very next page load and is gone if you refresh again.
• render :new, status: :unprocessable_entity — on failure, re-render the same form (not redirect anywhere) so @service — now populated with both what the user typed and the validation errors attached to it — can be shown back to them with their input intact and the specific problems called out. status: :unprocessable_entity sets the HTTP status code to 422 instead of the default 200; the browser still renders the HTML either way, but a 422 correctly tells any tooling watching the response (browser dev tools, Turbo, a test suite) that this was a failed submission, not a successful page load that happens to contain a form.
• private — everything below this line is only callable from within the controller itself, not reachable as a route.
• def service_params / params.require(:service).permit(:title, :description, :price, :category_id) — Rails’ strong parameters. params.require(:service) raises immediately if the submitted form data has no top-level service key at all (a malformed or missing request), and .permit(...) is an allowlist: only these four keys are allowed through; anything else present in the raw request params — including, say, a user_id someone tried to inject by editing the form’s HTML in their browser before submitting — is silently stripped and never reaches Service.new. Notice this permits :price, not :price_cents — the controller talks to the same euros-facing interface the form does; it has no idea price_cents exists either.

Routes and the two placeholder buttons

# config/routes.rb
resources :services, only: [:index, :new, :create]

resources :services is Rails’ RESTful routing shorthand — on its own it would generate all seven conventional routes (index, new, create, show, edit, update, destroy). only: [:index, :new, :create] narrows that down to exactly the three this episode implements. Running bin/rails routes -g services shows exactly what got generated:

     Prefix Verb URI Pattern             Controller#Action
   services GET  /services(.:format)     services#index
            POST /services(.:format)     services#create
new_service GET  /services/new(.:format) services#new

The Prefix column is where path helper names like services_path and new_service_path — used throughout the controller and views in this episode — come from: Rails derives them automatically from the prefix plus _path or _url. There’s no show route yet, on purpose — there’s no individual service page to link to until a later episode builds one.

Episode 1’s landing page shipped with two buttons that did nothing on purpose, styled to look disabled:

<span class="rounded-md bg-indigo-600 px-4 py-2 text-white font-medium opacity-60 cursor-not-allowed">
  Browse services
</span>
<span class="rounded-md border border-gray-300 px-4 py-2 text-gray-700 font-medium opacity-60 cursor-not-allowed">
  Offer a service
</span>

They finally go somewhere:

<%= link_to "Browse services", services_path, class: "rounded-md bg-indigo-600 px-4 py-2 text-white font-medium hover:bg-indigo-700" %>
<%= link_to "Offer a service", authenticated? ? new_service_path : new_registration_path, class: "rounded-md border border-gray-300 px-4 py-2 text-gray-700 font-medium hover:bg-gray-50" %>

Both <span> placeholders became link_to calls, and the opacity-60 cursor-not-allowed classes that visually signalled “not clickable yet” are gone along with the disabled state itself.

• link_to "Browse services", services_path, ... — unconditional. The index is public (allow_unauthenticated_access only: :index from the controller), so this link always makes sense, signed in or not.
• link_to "Offer a service", authenticated? ? new_service_path : new_registration_path, ... — the destination itself is a ternary. authenticated? is the helper_method episode 2’s Authentication concern exposes to views (it’s just resume_session, reused to answer “is anyone signed in” without triggering a redirect the way require_authentication would). Signed in, the link goes straight to new_service_path — the form. Signed out, it goes to new_registration_path — sign-up — instead of straight to the service form, which would just immediately bounce them to the sign-in page anyway via require_authentication. Same eventual destination either way; one fewer redirect for the common case of a visitor who isn’t signed in yet.

The “offer a service” form

<%# app/views/services/new.html.erb %>
<div class="max-w-xl mx-auto">
  <h1 class="text-3xl font-bold text-gray-900">Offer a service</h1>
  <p class="mt-2 text-gray-600">Tell your neighbours what you can help with.</p>

  <%= form_with model: @service, url: services_path, class: "mt-8 space-y-5" do |form| %>
    <% if @service.errors.any? %>
      <div class="rounded-md bg-red-50 px-4 py-3 text-sm text-red-700">
        <ul class="list-disc list-inside">
          <% @service.errors.full_messages.each do |message| %>
            <li><%= message %></li>
          <% end %>
        </ul>
      </div>
    <% end %>

    <div>
      <%= form.label :title, class: "block text-sm font-medium text-gray-700" %>
      <%= form.text_field :title, placeholder: "Guitar lessons for beginners", class: "mt-1 block w-full rounded-md border border-gray-300 px-3 py-2 focus:outline-none focus:ring-2 focus:ring-indigo-500" %>
    </div>

    <div>
      <%= form.label :category_id, "Category", class: "block text-sm font-medium text-gray-700" %>
      <%= form.collection_select :category_id, Category.order(:name), :id, :name, { prompt: "Choose a category" }, class: "mt-1 block w-full rounded-md border border-gray-300 px-3 py-2 focus:outline-none focus:ring-2 focus:ring-indigo-500" %>
    </div>

    <div>
      <%= form.label :description, class: "block text-sm font-medium text-gray-700" %>
      <%= form.text_area :description, rows: 4, placeholder: "What you offer, your experience, anything a neighbour should know.", class: "mt-1 block w-full rounded-md border border-gray-300 px-3 py-2 focus:outline-none focus:ring-2 focus:ring-indigo-500" %>
    </div>

    <div>
      <%= form.label :price, "Price (EUR)", class: "block text-sm font-medium text-gray-700" %>
      <%= form.text_field :price, placeholder: "45.00", inputmode: "decimal", class: "mt-1 block w-40 rounded-md border border-gray-300 px-3 py-2 focus:outline-none focus:ring-2 focus:ring-indigo-500" %>
    </div>

    <%= form.submit "Publish", class: "rounded-md bg-indigo-600 px-4 py-2 text-white font-medium hover:bg-indigo-700 cursor-pointer" %>
  <% end %>
</div>

• form_with model: @service, url: services_path, ... — model: @service is what makes this one form work for both a brand-new, unsaved Service (from ServicesController#new) and, later, one that failed to save and is being re-rendered with errors attached (from #create’s render :new) — Rails inspects whether the record is persisted to decide the form’s HTTP method, though since the routes only define create, this form only ever needs to POST. url: services_path is explicit here rather than left to be inferred, pointing the submission at the services#create route regardless.
• <% if @service.errors.any? %> ... @service.errors.full_messages.each ... <% end %> — after a failed create, @service carries whatever the user typed and the specific validation failures attached to it by save. errors.full_messages turns those into ready-to-read strings like “Title can’t be blank” — this is exactly the block that rendered the error lists shown further down this post.
• form.label :title, ... / form.text_field :title, ... — a standard labeled text input. form.label :title without an explicit label text infers “Title” from the attribute name automatically (via the same humanize mechanism discussed in the I18n section below); placeholder: is just an HTML attribute passed straight through.
• form.collection_select :category_id, Category.order(:name), :id, :name, { prompt: "Choose a category" }, class: "..." — this is the one helper in the form worth slowing down on, because it takes five separate arguments before the HTML options hash:
  1. :category_id — the attribute being set on submit (matches belongs_to :category’s foreign key column).
  2. Category.order(:name) — the collection of records to build <option> tags from, alphabetized so the dropdown doesn’t list categories in whatever order they happened to be seeded.
  3. :id — the value method: for each Category in the collection, call .id to get what actually gets submitted as category_id.
  4. :name — the text method: call .name to get what’s displayed to a human inside the dropdown.
  5. { prompt: "Choose a category" } — options for the select itself; prompt: inserts a disabled, unselected placeholder option with that text, so the dropdown doesn’t silently default to the first category in the list if someone submits without touching it. Only after that fifth argument does the ordinary class: "..." HTML-attributes hash appear — a collection_select call always separates “how to build the options” from “what HTML attributes to put on the <select> tag” this way.
• form.label :price, "Price (EUR)", ... — here the label text is given explicitly (“Price (EUR)”), overriding what humanize-from-attribute-name would have produced (“Price”), because the form needs to communicate the currency and the model attribute name has no way to carry that on its own.
• form.text_field :price, placeholder: "45.00", inputmode: "decimal", ... — this is the field that calls Service#price= on submit, not price_cents= — the view genuinely never mentions cents anywhere. inputmode: "decimal" is a plain HTML attribute (nothing Rails-specific) that hints mobile keyboards to show a numeric keypad with a decimal point instead of the full alphabetic keyboard.
• form.submit "Publish", ... — renders an <input type="submit"> with the given label; cursor-pointer is purely cosmetic, since a submit button is clickable by default but browsers don’t always render the pointer cursor on it without being told to.

The services listing

<%# app/views/services/index.html.erb %>
<div class="max-w-3xl mx-auto w-full">
  <% if notice = flash[:notice] %>
    <p class="py-2 px-3 bg-green-50 mb-5 text-green-700 font-medium rounded-lg inline-block" id="notice"><%= notice %></p>
  <% end %>

  <div class="flex items-center justify-between">
    <h1 class="text-3xl font-bold text-gray-900">Services near you</h1>
    <% if authenticated? %>
      <%= link_to "Offer a service", new_service_path, class: "rounded-md bg-indigo-600 px-4 py-2 text-white font-medium hover:bg-indigo-700" %>
    <% end %>
  </div>

  <% if @services.none? %>
    <p class="mt-8 text-gray-500">No services yet — be the first to offer one.</p>
  <% else %>
    <div class="mt-8 space-y-4">
      <% @services.each do |service| %>
        <div class="rounded-lg border border-gray-200 p-5">
          <div class="flex items-start justify-between gap-4">
            <div>
              <p class="text-xs font-semibold uppercase tracking-wide text-indigo-600"><%= service.category.name %></p>
              <h2 class="mt-1 text-lg font-semibold text-gray-900"><%= service.title %></h2>
              <p class="mt-1 text-sm text-gray-500">by <%= service.user.email_address %></p>
            </div>
            <p class="whitespace-nowrap text-lg font-semibold text-gray-900">
              <%= number_to_currency(service.price) %>
            </p>
          </div>
          <p class="mt-3 text-gray-600"><%= service.description %></p>
        </div>
      <% end %>
    </div>
  <% end %>
</div>

• <% if notice = flash[:notice] %> ... <% end %> — this is a single = on purpose, an assignment used as a condition, not a == comparison. flash[:notice] is read once, assigned to a local notice, and that same local is reused inside the block — this is the exact pattern already used in sessions/new.html.erb from episode 2, kept consistent here rather than introducing a different idiom. It’s what makes the “Your service is live.” message from the controller’s redirect_to ..., notice: "..." actually show up on screen — nothing renders flash automatically anywhere in this layout, each view that wants to show it does so explicitly.
• <% if authenticated? %> ... <% end %> around the “Offer a service” button — a signed-out visitor browsing the public index sees the listings but not an invitation to post one; the button only appears once someone is actually signed in.
• <% if @services.none? %> ... <% else %> ... <% end %> — .none? is a plain ActiveRecord/Enumerable query, true when the relation has zero records. This is the empty-state message, shown instead of an empty page with no explanation the first time the app runs with no listings yet.
• <% @services.each do |service| %> — iterates the eager-loaded relation from the controller. Because Service.includes(:category, :user) already pulled every category and user into memory alongside the services themselves, service.category.name and service.user.email_address inside this loop don’t trigger any additional queries — this is the payoff of the includes call discussed in the controller section landing here, in the view, where the N+1 would otherwise actually happen.
• service.category.name, service.title, service.user.email_address, service.description — straightforward attribute and association reads.
• number_to_currency(service.price) — a Rails view helper (from ActionView::Helpers::NumberHelper) that formats a plain number as currency: 42.5 becomes "€42.50" — the correct two decimal places and currency symbol, not whatever number of digits the float happens to have. This calls service.price, the euros-facing virtual reader defined on the model — not service.price_cents — so the number on screen is genuinely 42.5, formatted, never 4250.

Left completely unconfigured, number_to_currency defaults to US dollars — VicinoTe’s currency is euros, so that default needed overriding once, globally, rather than passing unit: "€" at every call site:

# config/locales/en.yml
en:
  number:
    currency:
      format:
        unit: "€"
        format: "%u%n"

unit: is the symbol itself. format: is the template that arranges it relative to the number — %u is the unit, %n is the formatted number, so "%u%n" means “symbol, then number, no space,” which is what produces €42.50 rather than € 42.50 or 42.50€. Both number_to_currency calls in the app — there’s only the one, in index.html.erb — pick this up automatically with no argument changes needed, because the default itself moved, not the call site.

A views-only gotcha: the error said “price cents”

Submitting the form empty for the first time, before fixing this, produced:

Category must exist
Title can't be blank
Description can't be blank
Price cents can't be blank
Price cents is not a number

Everything else reads naturally — “Title can’t be blank” — because Rails derives the human-readable label from the attribute name via humanize. But the attribute actually being validated is price_cents, not price, so that’s the name that leaked into the message. A user filling out this form has never heard of price_cents; the form field right below the error just says “Price (EUR)”.

The fix is a one-line I18n override, not a code change to the model — the validation is correct, only its rendered name was wrong:

# config/locales/en.yml
en:
  activerecord:
    attributes:
      service:
        price_cents: "Price"

This is Rails’ I18n lookup for human_attribute_name: before falling back to auto-humanize-ing an attribute name, ActiveRecord checks activerecord.attributes.<model>.<attribute> in the locale files, and uses whatever string is found there verbatim, for every message that mentions that attribute — validation errors, form.label with no explicit text, anywhere.

One detail that cost a second pass: writing the override as price (lowercase) produced “price can’t be blank” — lowercase, inconsistent with “Title” and “Description” right next to it. Rails’ default humanize capitalizes the first letter automatically as part of what it does; a custom I18n string is used exactly as written, with no capitalization applied on top of it. The fix was just capitalizing the override itself, "Price".

Trying it

bin/dev

Sign up (or sign in), click “Offer a service”, fill in a title, pick a category, write a description, and a price like 42.50. Submit, and it redirects to /services with “Your service is live.” in a flash banner, the listing right below it — category, title, whoever posted it, description, and €42.50, not 4250. Sign out and visit /services directly: still there, still public. Try /services/new while signed out and it redirects to sign-in, same as any other protected page. Submit the form with everything blank and every field’s own validation message shows up, in plain, correctly-capitalized English, “price_cents” nowhere in sight.

What’s next

Episode 4 builds Booking — the record of an agreement between two users, and the flow that actually lets someone book a service that’s been listed.

This episode fixes that: the reply now types itself onto the page as the model generates it, token by token, without a full page reload. Along the way we’re also closing a TODO left over from episode 3 — there was no way to start a fresh conversation; session[:conversation_id] just kept the same one forever.

Code is tagged episode-4 in the ai-with-ruby-demo repo. Fair warning up front: this episode hit two real bugs while building it, and I’m leaving both in the post with the exact error messages and the exact reasoning that led to the fix — that debugging trail is arguably more useful than the final code on its own.

How RubyLLM streams a response, from the inside

Before touching any of our own code, it’s worth opening RubyLLM’s source and reading ask and complete, because everything we build in this episode leans on their exact behavior. Here’s the relevant part of chat_methods.rb, the module acts_as_chat mixes into Conversation:

def ask(message = nil, with: nil, &)
  add_message(role: :user, content: build_content(message, with))
  complete(&)
end

def complete(...)
  to_llm.complete(...)
end

def setup_persistence_callbacks
  return @chat if @chat.instance_variable_get(:@_persistence_callbacks_setup)

  @chat.before_message { persist_new_message }
  @chat.after_message { |msg| persist_message_completion(msg) }

  @chat.instance_variable_set(:@_persistence_callbacks_setup, true)
  @chat
end

def persist_new_message
  @message = messages_association.create!(role: :assistant, content: '')
end

Four things fall out of this that matter a lot for what we’re about to build:

1. ask persists the user’s message itself, synchronously, before doing anything else. If your own code also inserts a user Message row before calling ask, you get two rows for one question — we’ll see exactly this mistake below.
2. The empty assistant message is created before any text exists. persist_new_message runs in a before_message callback and creates a Message with content: ''. So by the time the model starts talking, there’s already a row in the database — with an id — waiting to be filled in.
3. ask/complete accept a block, and that block is RubyLLM’s streaming hook — it’s invoked once per chunk of text as the provider streams it back, well before the reply is complete.
4. The final content is written once, at the end, by persist_message_completion, in an after_message callback — a normal UPDATE on the same row that was created empty.

Put together: one .ask(content, &block) call creates two rows (user, then empty assistant), then calls your block repeatedly as chunks arrive, then does one final UPDATE with the complete text and the token counts. Nothing about persistence changes if you pass a block — the only thing a block adds is a callback fired per chunk. Streaming, in other words, isn’t a different code path; it’s the exact same ask we’ve used since episode 3, with a block attached.

The plan: a background job, not a slower controller action

The request/response cycle is fundamentally the wrong shape for this. An HTTP response has to finish before the browser can render it — you can’t dribble a Rails view out a few words at a time over a normal render. So the LLM call has to move off the request entirely, into a background job, and the job has to push each chunk to the browser through a side channel as it arrives. In a Rails 8 app, that side channel is Turbo Streams delivered over Action Cable — no separate JavaScript framework, no manual WebSocket wiring.

Rather than inventing this pattern by hand, I went to see how RubyLLM itself recommends doing it. The gem ships a generator, ruby_llm:chat_ui, built for exactly this. Running it with --pretend (nothing gets written to disk) against our own app, remapped to our actual model name:

bin/rails generate ruby_llm:chat_ui chat:Conversation --pretend

create  app/views/conversations/{index,new,show,_conversation,_form}.html.erb
create  app/views/messages/{_assistant,_user,_system,_tool,_error,_content,_form}.html.erb
create  app/views/messages/tool_calls/_default.html.erb
create  app/views/messages/tool_results/_default.html.erb
create  app/views/messages/create.turbo_stream.erb
create  app/views/models/{index,show,_model}.html.erb
create  app/controllers/conversations_controller.rb
create  app/controllers/messages_controller.rb
create  app/controllers/models_controller.rb
create  app/jobs/conversation_response_job.rb
insert  app/models/message.rb
 route  resources :conversations { resources :messages, only: [:create] }
 route  resources :models, only: [:index, :show] { collection { post :refresh } }

That’s a full multi-conversation CRUD scaffold — an index and a show page per conversation, a controller for browsing available Model records, views for tool calls and tool results (for a tool-calling episode we haven’t written yet). Our app deliberately isn’t shaped like that: since episode 3 there’s exactly one implicit conversation per browser session, no listing, no separate show page. Adopting the whole scaffold would mean rewriting the app’s shape to fit the generator, not the other way around.

So instead of running it, I read the templates and pulled out the three pieces that are actually about streaming, adapted to keep episode 3’s session-based, single-conversation design:

• A model concern that lets a Message broadcast itself over Turbo Streams.
• A background job that calls ask with a block and forwards each chunk to the browser.
• A controller that enqueues the job and gets out of the way immediately.

Making Message broadcast itself

# app/models/message.rb
class Message < ApplicationRecord
  acts_as_message chat: :conversation

  broadcasts_to ->(message) { "conversation_#{message.conversation_id}" }, inserts_by: :append

  def broadcast_append_chunk(content)
    broadcast_append_to "conversation_#{conversation_id}",
      target: "message_#{id}_content",
      content: ERB::Util.html_escape(content.to_s)
  end
end

broadcasts_to is Turbo Streams’ own ActiveRecord integration (from the turbo-rails gem, not RubyLLM), and it’s doing more than the one line suggests. Its actual definition, in turbo/broadcastable.rb:

def broadcasts_to(stream, inserts_by: :append, target: broadcast_target_default, **rendering)
  after_create_commit  -> { broadcast_action_later_to(stream.try(:call, self) || send(stream), action: inserts_by, target: target.try(:call, self) || target, **rendering) }
  after_update_commit  -> { broadcast_replace_later_to(stream.try(:call, self) || send(stream), **rendering) }
  after_destroy_commit -> { broadcast_remove_to(stream.try(:call, self) || send(stream)) }
end

So one call to broadcasts_to wires up three callbacks, not one:

• On create, append a rendered copy of the message into the stream, at target: (defaulting to model_name.plural, i.e. "messages" — the id of a container element the page needs to provide).
• On update, replace the message’s own element (default target: itself, dom_id(message)) with a freshly rendered copy.
• On destroy, remove it.

That middle one matters a lot here, and it’s easy to miss on a first read: every time a Message row is updated — including the final persist_message_completion update that writes the complete text — the whole message bubble gets replaced with a fresh render. That’s a nice safety net: it means the very last update always overwrites whatever the incremental appends left behind with an authoritative, freshly-rendered copy from the database. It also means an incidental update (as we’ll see below) can trigger a broadcast you didn’t ask for.

broadcast_append_chunk is ours, not Turbo’s — it’s not appending a new message, it’s appending raw text into a message that already exists, targeting a specific inner <div> (message_#{id}_content) rather than the outer message container. ERB::Util.html_escape matters here: chunk content comes straight from the model, unescaped, and this is rendering raw HTML into the page — skip the escape and a reply containing < or & would corrupt the markup (or, worse, become an injection vector if the model ever echoed back something a user typed).

The background job

# app/jobs/conversation_response_job.rb
class ConversationResponseJob < ApplicationJob
  def perform(conversation_id, content)
    conversation = Conversation.find(conversation_id)
    assistant_message = nil

    conversation.ask(content) do |chunk|
      next if chunk.content.blank?

      assistant_message ||= conversation.messages.last
      assistant_message.broadcast_append_chunk(chunk.content)
    end
  end
end

This is almost the generator’s own job, with one deliberate change. The generator’s version calls conversation.messages.last inside the block, on every single chunk — a fresh SQL query per chunk, for a message that never changes across the whole call. We already know from the ask/complete walkthrough above exactly when that assistant message is created: in the before_message callback, which fires once, before the first chunk is ever yielded. So the row exists and its id is fixed before our block runs even once — there’s nothing to look up again after the first chunk. assistant_message ||= conversation.messages.last fetches it once and reuses the same in-memory record for every subsequent broadcast_append_chunk call.

chunk.content.blank? guards against chunks that carry metadata but no text (some providers stream a final chunk with usage stats and an empty content) — nothing to append, and nothing to broadcast.

The controller: enqueue, then get out of the way

# app/controllers/chats_controller.rb
class ChatsController < ApplicationController
  def new
    @conversation = current_conversation
  end

  def create
    ConversationResponseJob.perform_later(current_conversation.id, params[:message])

    respond_to do |format|
      format.turbo_stream
      format.html { redirect_to new_chat_path }
    end
  end

  def destroy
    session.delete(:conversation_id)
    redirect_to new_chat_path
  end

  private

  def current_conversation
    Conversation.find_by(id: session[:conversation_id]) || create_conversation
  end

  def create_conversation
    conversation = Conversation.create!
    session[:conversation_id] = conversation.id
    conversation
  end
end

The first version of this method I wrote also created the user’s Message row directly in the controller, before enqueuing the job — the mistake mentioned at the very top of this post. ask already does that internally, so the row I was adding by hand was a genuine second, duplicate user message for the same question. The fix was just deleting that line; ConversationResponseJob.perform_later is enough, since conversation.ask(content) inside the job creates it.

create no longer redirects on success. Episode 3’s Post/Redirect/Get pattern doesn’t disappear — it’s still there as the format.html fallback for a plain, non-JS request — but with Turbo doing its job, the request that submits the form gets a format.turbo_stream response instead, and the page itself never reloads. Everything the user sees afterward — their own message appearing, the assistant bubble appearing empty, the text typing itself in — arrives later, over the already-open Action Cable connection, not as part of this response.

destroy is the whole fix for episode 3’s leftover TODO: forget the conversation id in the session and go back to new, which creates a fresh one. Wiring it into the routes needed one word:

# config/routes.rb
resource :chat, only: [:new, :create, :destroy]

The turbo_stream response: clearing the form

<%# app/views/chats/create.turbo_stream.erb %>
<%= turbo_stream.replace "new_message" do %>
  <%= render "form" %>
<% end %>

This is the entire HTTP response body to a POST /chat now. It doesn’t touch the conversation or the messages at all — its only job is to swap in a fresh, empty form, so the textarea clears itself after sending. Everything else happens later, over the cable connection, from the background job.

The form itself got pulled into its own partial so this response (and the initial page) can both render it:

<%# app/views/chats/_form.html.erb %>
<div id="new_message">
  <%= form_with url: chat_path, method: :post, class: "flex flex-col gap-3" do %>
    <textarea
      name="message"
      rows="3"
      placeholder="Ask something..."
      class="border border-gray-300 rounded-md p-3 focus:outline-none focus:ring-2 focus:ring-indigo-500"
    ></textarea>

    <button
      type="submit"
      class="self-start bg-indigo-600 text-white px-4 py-2 rounded-md hover:bg-indigo-700"
    >
      Send
    </button>
  <% end %>
</div>

The id="new_message" on the wrapping div is what turbo_stream.replace "new_message" targets.

Bug #1: rendering messages by role, and a variable name that changes underneath you

Episode 3’s view looped over @conversation.messages by hand and branched on message.role inline to pick styling. That doesn’t work once other code — broadcasts_to — needs to render a Message on its own, without our view’s loop around it. So this episode moves rendering into partials, and render @conversation.messages uses Rails’ standard partial-per-record convention: for a Message, that would normally mean messages/_message.html.erb. I wrote exactly that partial first, and got this:

ActionView::MissingTemplate in Chats#new
Missing partial messages/_user with {locale: [:en], formats: [:html], ...}

Not _message — _user. The reason is in RubyLLM’s own Message concern, message_methods.rb:

def to_partial_path
  partial_prefix = self.class.name.underscore.pluralize
  role_partial = if to_llm.tool_call?
                   'tool_calls'
                 elsif role.to_s == 'tool'
                   'tool'
                 else
                   role.to_s.presence || 'assistant'
                 end
  "#{partial_prefix}/#{role_partial}"
end

RubyLLM overrides to_partial_path so a Message picks its own partial by role — messages/user, messages/assistant, and so on. That’s exactly why the official generator ships separate _user.html.erb, _assistant.html.erb, _system.html.erb, _tool.html.erb partials instead of one generic one: it has to, this override forces it. So the fix was renaming the file — messages/_user.html.erb and messages/_assistant.html.erb — not changing anything about the render call.

That fixed the missing-template error, but not the page. Reloading gave a different one:

NameError in Chats#new
undefined local variable or method 'user' for an instance of #<Class:0x...>

I’d written the partial expecting a local called message (the natural name, matching the variable everywhere else in this app):

<div id="<%= dom_id(message) %>" class="text-right">
  ...

But when Rails renders a partial resolved through to_partial_path, it names the local after the partial, not the class — for messages/_user.html.erb, that’s user, not message. I fixed the name and moved on, confident that was the whole story. It wasn’t.

Bug #2: the same partial, rendered two different ways, with two different local names

Everything looked right after that fix — until I actually sent a message and watched the live broadcasts (the ones fired by broadcasts_to, not the initial page render) blow up in the server log:

Error performing Turbo::Streams::ActionBroadcastJob ...:
ActionView::Template::Error (undefined local variable or method 'user' for an instance of #<Class:0x...>):
app/views/messages/_user.html.erb:2

Same error, same file — but the initial page render, moments earlier in the very same log, had worked fine with the exact same partial. Two different code paths were rendering messages/_user.html.erb with two different sets of locals. render @conversation.messages (a collection) infers the local’s name from the resolved partial path — user. But broadcasts_to’s after_update_commit callback (the one triggered by that incidental content_raw update inside add_message, mentioned above) calls broadcast_replace_later_to, which renders the same partial with an explicit locals: {message: ...} — the local is named after the model class, not the partial.

Same partial file, two callers, two different local variable names for the exact same object. The fix is a defensive first line, reading whichever one is actually present:

<%# app/views/messages/_user.html.erb %>
<% user = local_assigns[:user] || local_assigns[:message] %>
<div id="<%= dom_id(user) %>" class="text-right">
  <p class="text-xs text-gray-500 mb-1">user</p>
  <div id="<%= dom_id(user) %>_content" class="inline-block rounded-md px-3 py-2 bg-indigo-600 text-white">
    <%= user.content %>
  </div>
</div>

<%# app/views/messages/_assistant.html.erb %>
<% assistant = local_assigns[:assistant] || local_assigns[:message] %>
<div id="<%= dom_id(assistant) %>" class="text-left">
  <p class="text-xs text-gray-500 mb-1">assistant</p>
  <div id="<%= dom_id(assistant) %>_content" class="inline-block rounded-md px-3 py-2 bg-gray-100">
    <%= assistant.content %>
  </div>
</div>

This is exactly the shape of the fallback in RubyLLM’s own generated partial (assistant ||= local_assigns[:message]) — I hadn’t noticed why it was there until I hit the same wall myself. Reading generated code before you need it and reading it after it just broke your page teach very different lessons; this was the second kind.

The container the initial render @conversation.messages needs, and the one broadcasts_to’s create-time append (target defaults to model_name.plural, "messages") needs to find already on the page:

<%# app/views/chats/new.html.erb — excerpt %>
<div id="messages" class="space-y-4 mb-8">
  <%= render @conversation.messages %>
</div>

Bug #3 (the real one): two different names for the same stream

With both partials fixed, I reloaded, sent a message, and — nothing. No error anywhere. The form cleared (so the turbo_stream response from create had worked). But no user bubble, no assistant bubble, not even after several seconds, not even after the background job had clearly finished (I could see the full reply, correctly saved, by refreshing the page).

The Rails log told a completely clean story: the job ran, conversation.ask created both rows, every Turbo::Streams::ActionBroadcastJob performed successfully, and line after line of [ActionCable] Broadcasting to conversation_7: ... showed every single chunk going out, right down to the very last one. Server-side, everything worked. The browser just never got any of it.

I checked the page itself with a bit of JavaScript, from the browser console:

const el = document.querySelector('turbo-cable-stream-source');
el.hasAttribute('connected')   // true
el.subscription                // present

Connected, subscribed, no console errors — and still nothing arriving. At this point the two sides looked individually correct and mutually unreachable, which is exactly what happens when they’re each listening to / broadcasting on a different stream that merely looks the same to a human reading the code.

The subscription lives in the view:

<%= turbo_stream_from @conversation %>

I’d written this the way you’d write it if you’d only ever seen turbo_stream_from used with a plain ActiveRecord object — pass the record, done. And it is valid — turbo_stream_from accepts any “streamable”, including a model instance, and derives a stream name from it (based on its GlobalID). The problem is that @conversation was never the identifier used anywhere else in this episode. broadcasts_to and broadcast_append_chunk, back in the Message model, both build the stream name from a plain string:

"conversation_#{message.conversation_id}"

A string and a model object don’t hash to the same signed stream name just because a human reads them as “the same conversation.” turbo_stream_from @conversation and broadcasts_to ->(message) { "conversation_#{message.conversation_id}" } were quietly subscribing to and broadcasting on two entirely different channels — no error on either side, because neither side does anything wrong in isolation; they just never meet.

The generator’s own view template settled it for me — chats/show.html.erb.tt:

<%%= turbo_stream_from "<%= chat_variable_name %>_#{@<%= chat_variable_name %>.id}" %>

A string, built the same way as the model’s. Matching that:

<%= turbo_stream_from "conversation_#{@conversation.id}" %>

One line, and every broadcast that had been silently going nowhere started arriving instantly. The lesson underneath the bug: turbo_stream_from and broadcasts_to don’t have to agree on how you name a stream — object or string, doesn’t matter which — but every subscriber and every broadcaster absolutely have to agree with each other, exactly, because there’s no error path when they don’t. It fails by going quiet, not by raising.

The complete, working view:

<%# app/views/chats/new.html.erb %>
<div class="max-w-xl mx-auto mt-16 px-4">
  <div class="flex items-center justify-between mb-6">
    <h1 class="text-2xl font-semibold">RubyLLM chat demo</h1>
    <%= button_to "New conversation", chat_path, method: :delete, class: "text-sm text-gray-500 hover:text-gray-700" %>
  </div>

  <%= turbo_stream_from "conversation_#{@conversation.id}" %>

  <div id="messages" class="space-y-4 mb-8">
    <%= render @conversation.messages %>
  </div>

  <%= render "form" %>
</div>

Trying it in the browser

bin/dev

Open http://127.0.0.1:3000, ask something, and this time the reply doesn’t just appear — it fills in progressively, the way a chat app is supposed to feel. Here’s a real exchange from testing this episode, captured mid-session:

Unplanned, but fitting: I asked for a pep talk about debugging ActionCable, and the reply landed on “check that the stream name matches exactly” — the exact bug from the section above.

A longer session, showing the “New conversation” link (top right) that closes out episode 3’s TODO, and multiple exchanges accumulating in the same conversation:

A caveat worth knowing: broadcast ordering isn’t guaranteed

While capturing that second screenshot, I hit something worth flagging rather than quietly editing around. broadcasts_to’s after_create_commit callback doesn’t broadcast synchronously — it calls broadcast_action_later_to, which enqueues another background job (Turbo::Streams::ActionBroadcastJob) to do the actual rendering and broadcasting. So a single .ask call, under the hood, enqueues several jobs in quick succession: one to append the user message, one (from the incidental content_raw update) to replace it again, one to append the empty assistant message, plus one more at the very end to replace it with the finished text.

With Rails’ default :async queue adapter — a small in-process thread pool — these aren’t strictly guaranteed to finish in the order they were enqueued. In one live test I watched an assistant’s reply render before the user question it was answering, purely because that append job happened to finish on a different thread a few milliseconds sooner. Refreshing the page immediately showed the correct order — messages are always fetched with ORDER BY created_at, so the database is never wrong, only a specific live-updating page can briefly show things out of sequence. In production, with a real queue (Solid Queue, already configured in this app) this is far less likely to be visible at normal typing-and-reading speed, but it isn’t structurally impossible either. Not something this episode fixes — just something worth knowing is there if a message ever seems to jump the queue on screen.

What’s next

Episode 5 covers semantic search: turning Message content into embeddings, and letting a user search across past conversations by meaning, not just exact words.

Code is tagged episode-2 in the whatsapp-with-rails repo. This is a long one — the goal is to leave nothing unexplained: every gem, every line of every migration, every line of the model and controller, and the exact errors you’ll hit and why.

What the WhatsApp Sandbox actually is, and why you need it

Sending a WhatsApp message through the real WhatsApp Business Platform requires a phone number registered and approved through Meta — a process with review steps and waiting time. Twilio’s Sandbox exists so you don’t have to go through that just to write and test code. It’s a shared, pre-approved Twilio number (+14155238886 for everyone using Twilio’s sandbox) that can send and receive WhatsApp messages immediately, with one restriction: it will only talk to phone numbers that have explicitly joined it.

Joining means sending a specific message — join <two-word-code>, e.g. join vowel-purpose, a code Twilio generates per account — from WhatsApp, from the phone number you want to test with, to that sandbox number. You can do this by hand from WhatsApp, or by opening the link/QR code Twilio’s console shows you (Console → Messaging → Try it out → Send a WhatsApp message). Once a number joins, Twilio can send it messages via the API; a number that never joined will reject them, every time, with an error we’ll walk through further down.

Two details worth knowing, because you’ll run into both eventually:

• The join lasts 3 days of inactivity, not forever. If nobody sends anything to the sandbox from that number for 3 days, it has to join again.
• This is strictly a testing mechanism. In production you send from a WhatsApp-enabled sender you own (still set up through Twilio, but without the “only pre-joined numbers” restriction) — the sandbox is for development, not for talking to real customers.

The two gems

# Gemfile
gem "twilio-ruby"

group :development do
  gem "web-console"
  gem "dotenv-rails"
end

twilio-ruby is Twilio’s official Ruby client — a wrapper around Twilio’s REST API, giving you Twilio::REST::Client.new(...).messages.create(...) instead of hand-building HTTP requests and parsing JSON. dotenv-rails, same as in the ai-with-ruby series, loads a .env file into ENV in development, so credentials live outside the codebase.

bundle install

Credentials: .env, .env.example, and .gitignore

Three real values are needed, all secrets: your Twilio Account SID, your Auth Token, and the sandbox WhatsApp number. Rails 8’s default .gitignore already excludes .env*, so a real .env file never gets committed. We commit a template instead:

# .env.example
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your-auth-token-here
TWILIO_WHATSAPP_NUMBER=+14155238886

Because .gitignore’s /.env* pattern is broad enough to also catch .env.example, it needs an explicit exception — this exact gotcha showed up already in the ai-with-ruby series:

# .gitignore
/.env*
!/.env.example

To actually run this app, copy the template and fill in real values:

cp .env.example .env

On the Account SID and Auth Token specifically: these are your Twilio account’s master credentials — anyone with them can send messages (and be billed) as you. They’re found on the main Twilio Console dashboard the moment you log in. If you ever paste one somewhere public by accident, Twilio lets you regenerate the Auth Token from the console; the old one stops working immediately.

The Twilio client: one initializer, one line

# config/initializers/twilio.rb
Rails.application.config.x.twilio_client = Twilio::REST::Client.new(
  ENV.fetch("TWILIO_ACCOUNT_SID"),
  ENV.fetch("TWILIO_AUTH_TOKEN")
)

Same reasoning as the RubyLLM initializer in the AI with Ruby series: files in config/initializers/ run once, at boot, before any request — the right place to construct something that talks to a third-party API and hand it your credentials.

Two things worth being precise about here. First, ENV.fetch("TWILIO_ACCOUNT_SID") — no default given as a second argument — raises if the variable is missing, rather than silently continuing with nil. That’s deliberate: a misconfigured Twilio client that quietly does nothing is much harder to debug than an app that refuses to boot with a clear KeyError. Second, Rails.application.config.x is Rails’ built-in namespace for custom application configuration — the x stands for “custom”, and it exists specifically so you’re not tempted to stash app-specific config in global constants or Rails.application.config directly (which Rails itself uses). Anywhere in the app, Rails.application.config.x.twilio_client gets you the same configured client.

The Message model, and the migration behind it

bin/rails generate model Message contact:references body:text twilio_sid:string status:string

The generator produced a migration that I then edited before running it — worth going through both versions, because the edit is where the real thinking is:

# db/migrate/..._create_messages.rb — as generated
create_table :messages do |t|
  t.references :contact, null: false, foreign_key: true
  t.text :body
  t.string :twilio_sid
  t.string :status

  t.timestamps
end

# db/migrate/..._create_messages.rb — as run
create_table :messages do |t|
  t.references :contact, null: false, foreign_key: true
  t.text :body, null: false
  t.string :twilio_sid
  t.string :status, null: false, default: "queued"

  t.timestamps
end

Going column by column:

• t.references :contact, null: false, foreign_key: true — this is what the contact:references argument to the generator produces on its own: an integer contact_id column, a database-level index on it, a database-level foreign key constraint (foreign_key: true) so the database itself refuses to let a Message point at a Contact that doesn’t exist, and null: false because a message with no contact makes no sense.
• t.text :body, null: false — text rather than string because a message body has no natural short length limit the way a name does; I added null: false by hand because the generator doesn’t add presence constraints on its own, and an empty message is never something we want to send.
• t.string :twilio_sid — deliberately nullable. This gets filled in after Twilio accepts the message (more on this below); before that point, there’s a real Message row with no SID yet.
• t.string :status, null: false, default: "queued" — the one substantive change. I added null: false, default: "queued" so every Message has a sensible status the instant it’s created, before we’ve even talked to Twilio. Why this column exists at all is the more interesting question, covered in the next section.

# app/models/message.rb
class Message < ApplicationRecord
  belongs_to :contact

  validates :body, presence: true

  def deliver!
    twilio_message = Rails.application.config.x.twilio_client.messages.create(
      from: "whatsapp:#{ENV.fetch('TWILIO_WHATSAPP_NUMBER')}",
      to: "whatsapp:#{contact.whatsapp_number}",
      body: body
    )

    update!(twilio_sid: twilio_message.sid, status: twilio_message.status)
  end
end

belongs_to :contact is enough on its own to require a contact — Rails 5+ makes belongs_to associations required by default, so this line alone gives us most of what null: false in the migration was already doing, at the application level.

validates :body, presence: true mirrors the null: false on body — one is the database refusing invalid data no matter what inserts it, the other is a friendly validation error before we even try, which is what lets MessagesController show “can’t be blank” in the form instead of a database-level crash.

deliver! is the one method actually doing something. Look closely at from: and to: — WhatsApp numbers in the Twilio API are always prefixed with the literal string whatsapp:, e.g. whatsapp:+14155238886. This is how Twilio’s unified messaging API tells the difference between sending the same number as a WhatsApp message versus a plain SMS — the prefix, not a separate endpoint. Forget it on either side and the call either errors or silently tries to send a regular text message instead.

The naming convention — deliver!, with a bang — mirrors Rails’ own convention for methods that do something with real, possibly-failing side effects (save!, create!), as opposed to a quiet query. Sending a WhatsApp message is about as real a side effect as a method can have.

Why twilio_sid and status exist: WhatsApp sending is asynchronous

This is worth being explicit about, because it’s easy to assume a successful API call means the message arrived — it doesn’t. When messages.create returns without raising, all it means is: Twilio accepted the request and queued it for delivery. The status Twilio returns at that point is typically "queued", not "delivered". What actually happens to the message after that — sent, delivered, read, or failed — happens asynchronously, and by default your Rails app never hears about it again unless it asks.

That’s the whole reason twilio_sid and status are columns on Message rather than being thrown away after the API call: twilio_sid is the identifier Twilio gives back (SM...), and it’s how you look the message up again later to check what actually happened to it. I did exactly that while testing this episode:

fresh = Rails.application.config.x.twilio_client.messages(message.twilio_sid).fetch
fresh.status        # => "failed" — updated after the fact, not from the original response
fresh.error_code     # => 63015

The right way to keep status current without polling by hand is a status callback webhook — a URL you give Twilio that it POSTs to every time a message’s status changes. That’s genuinely more machinery (a public endpoint, a route, request verification) than belongs in an episode about the first successful send, so it’s out of scope here — but it’s worth knowing status exists on this model specifically because that future webhook will have something to update.

Wiring it into the app: routes, controller, contact list

# config/routes.rb
resources :contacts, only: [:index, :new, :create] do
  resources :messages, only: [:new, :create]
end

Nested resources here aren’t decoration — messages genuinely doesn’t make sense without a contact in context; there’s no “compose a message” screen that isn’t already about a specific person. This generates paths like new_contact_message_path(contact) and contact_messages_path(contact), both carrying the contact’s id.

# app/controllers/messages_controller.rb
class MessagesController < ApplicationController
  before_action :set_contact

  def new
    @message = @contact.messages.new
  end

  def create
    @message = @contact.messages.new(message_params)

    if @message.save
      begin
        @message.deliver!
        redirect_to contacts_path, notice: "Message sent to #{@contact.name}."
      rescue Twilio::REST::RestError => e
        redirect_to contacts_path, alert: "Twilio couldn't send the message: #{e.error_message}"
      end
    else
      render :new, status: :unprocessable_entity
    end
  end

  private

  def set_contact
    @contact = Contact.find(params[:contact_id])
  end

  def message_params
    params.require(:message).permit(:body)
  end
end

before_action :set_contact runs before both actions, loading @contact from params[:contact_id] — the nested route parameter, not :id (that would be the message’s own id, which doesn’t exist yet for new/create).

create does three things in order: build the Message (not yet saved), save it to the database, then attempt delivery. This ordering matters — the message exists as a database row, with status: "queued" from the column default, even before we know whether Twilio will accept it. If the process crashed between save and deliver, there’d still be a record of an intended message, not silence.

The synchronous failure case: Twilio::REST::RestError

Here’s something I only found by actually breaking it while testing: deliver! can fail in two completely different ways, and only one of them is visible where you’d expect.

Asynchronous failure — the number never joined the sandbox, the message gets rejected somewhere downstream — doesn’t raise anything in Rails at all. messages.create returns successfully with status: "queued"; the failure only shows up later if you go back and check, exactly as described above. I hit this directly: sending to a contact whose number had never sent join <code> to the sandbox came back as a normal, non-raising queued response from the app’s point of view, and only turned out to be status: "failed", error_code: 63015 when I fetched the message back from Twilio afterward. Error 63015, specifically, means “this recipient hasn’t joined this sandbox” — the single most common thing you’ll hit while testing this integration, and worth recognizing on sight.

Synchronous failure is different: bad credentials, a malformed request, anything Twilio’s API rejects immediately. That does raise, as Twilio::REST::RestError — I confirmed this directly, deliberately constructing a client with a wrong Account SID and Auth Token and watching it raise on the API call:

bad_client = Twilio::REST::Client.new("AC0000000000000000000000000000000", "wrongtoken")
bad_client.messages.create(from: "whatsapp:+14155238886", to: "whatsapp:+391234567890", body: "test")
# raises Twilio::REST::RestError
# e.status_code    => 401
# e.error_message  => "Authentication Error - invalid username"

Before adding the rescue you see in the controller above, this class of error would have bubbled straight up through deliver!, through create, into an unhandled 500, in what’s meant to be a demo shown to a client. rescue Twilio::REST::RestError => e catches it and redirects with a readable alert instead — e.error_message is the human-readable string Twilio itself sends back, so the message shown is Twilio’s own explanation, not a guess on our part.

What this episode does not do is turn the asynchronous 63015 case into a nice UI message — that’s not possible from inside create at all, since the app has already gotten a “successful”, queued response by the time the real failure happens. Handling that properly means the status callback webhook mentioned above; noting it here so it’s clear this is a known, deliberate gap, not an oversight.

Trying it

bin/dev

Add a contact with a WhatsApp number that has actually joined your sandbox (see the join instructions earlier in this post — a number that hasn’t joined will accept the send from the app’s perspective and then fail invisibly, exactly as described above). Click “Message” next to them, write something, send it.

Here’s the real result from testing this for the post — an actual message, sent from this actual code, received on an actual phone:

Twilio: Test from whatsapp-with-rails episode 2 🎉

If you try sending to a contact whose number never joined the sandbox, you’ll get queued in the app and nothing on the phone — that’s error 63015 waiting to be discovered if you check the message status afterward, not a bug in this code.

What’s next

Episode 3 does the same job a different way: calling Meta’s WhatsApp Cloud API directly, with no Twilio in between, so the trade-off between the two approaches — Twilio’s simplicity versus one less service in the middle — shows up in actual code, not just in the abstract.

Code is tagged episode-2 in the vicinote-tutorial repo.

Not Devise

Every past version of “add authentication to a Rails app” started with gem "devise". Rails 8 changed that: there’s now a built-in generator, bin/rails generate authentication, that writes plain, ordinary Rails code — models, controllers, a concern — directly into your app. No gem, no engine, no generated code living somewhere in a gem you can’t easily read.

That distinction matters more than it sounds. With Devise, understanding “how sign-in actually works” means reading the gem’s source. With the Rails 8 generator, the code it writes is your code, sitting in app/ like everything else, ready to be read, modified, and — as we’ll see partway through this episode — extended, because the generator deliberately doesn’t do everything.

bin/rails generate authentication

Here’s the full list of what that one command produced:

create  app/views/passwords/new.html.erb
create  app/views/passwords/edit.html.erb
create  app/views/sessions/new.html.erb
create  app/models/session.rb
create  app/models/user.rb
create  app/models/current.rb
create  app/controllers/sessions_controller.rb
create  app/controllers/concerns/authentication.rb
create  app/controllers/passwords_controller.rb
create  app/mailers/passwords_mailer.rb
create  app/views/passwords_mailer/reset.html.erb
create  app/views/passwords_mailer/reset.text.erb
insert  app/controllers/application_controller.rb
 route  resources :passwords, param: :token
 route  resource :session
  gsub  Gemfile
  create  db/migrate/..._create_users.rb
  create  db/migrate/..._create_sessions.rb

Worth reading every one of these before writing anything of our own, because — unlike a gem — we’re going to be looking directly at this code for the rest of the series.

The User model

# app/models/user.rb
class User < ApplicationRecord
  has_secure_password
  has_many :sessions, dependent: :destroy

  normalizes :email_address, with: ->(e) { e.strip.downcase }
end

has_secure_password is the one line doing the heavy lifting, and it’s not a Devise-style black box — it’s plain Rails, from ActiveModel::SecurePassword. It expects a password_digest column, adds password=/password_confirmation= virtual attributes that hash with bcrypt on assignment, and adds an authenticate instance method. We’ll come back to it below, because it does more than that — the password reset mechanism later in this post comes from the exact same line.

(Worth being precise about one thing: has_secure_password itself is Rails code, part of the activemodel gem — not part of bcrypt. The bcrypt gem in the Gemfile only supplies the BCrypt::Password class Rails uses internally to actually hash and compare passwords; the macro, the validations, and the reset-token logic all live in Rails itself, readable like any other framework code.)

normalizes :email_address is a smaller but genuinely useful Rails feature: it guarantees "Mario@Example.com " and "mario@example.com" are treated as the same address everywhere — on save, and on every subsequent lookup — without us having to remember to call .downcase.strip by hand at every call site.

# db/migrate/..._create_users.rb
create_table :users do |t|
  t.string :email_address, null: false
  t.string :password_digest, null: false
  t.timestamps
end
add_index :users, :email_address, unique: true

Note what’s not here: no name, no role, nothing marketplace-specific. This is intentionally the minimum viable authenticatable record. Everything from episode 1’s domain design — has_many :services, has_many :bookings — gets added when we actually build Service and Booking, not now. Adding those associations today would technically work (Rails resolves association class names lazily), but it would be code referring to models that don’t exist yet, which is worse for anyone reading this repo top to bottom.

Sessions and Current: how “who’s logged in” is tracked

This is the part that looks the most different from what you’d expect coming from Devise, and it’s worth slowing down on.

# app/models/session.rb
class Session < ApplicationRecord
  belongs_to :user
end

# db/migrate/..._create_sessions.rb
create_table :sessions do |t|
  t.references :user, null: false, foreign_key: true
  t.string :ip_address
  t.string :user_agent
  t.timestamps
end

A Session is a database row, not just an encrypted cookie. Every time someone signs in, a new Session record gets created, storing which user, from what IP, with what browser. The browser only ever holds the session’s id, signed inside a cookie so it can’t be tampered with — the actual session state lives server-side.

The practical upside: you can see every active session for a user (user.sessions), and revoke one individually — sign a specific device out — just by deleting that row. A pure cookie-based session can’t do that; you can only invalidate all sessions at once (e.g. by rotating a secret).

# app/models/current.rb
class Current < ActiveSupport::CurrentAttributes
  attribute :session
  delegate :user, to: :session, allow_nil: true
end

ActiveSupport::CurrentAttributes is a Rails mechanism for per-request global state — safer than a plain global variable because it’s automatically reset between requests (and between test cases), so there’s no risk of one request’s user leaking into the next. Current.session holds the current Session record for this request; Current.user is just Current.session.user, available anywhere in the app via Current.user, no need to pass it down through every method call.

The Authentication concern: secure by default

# app/controllers/concerns/authentication.rb
module Authentication
  extend ActiveSupport::Concern

  included do
    before_action :require_authentication
    helper_method :authenticated?
  end

  class_methods do
    def allow_unauthenticated_access(**options)
      skip_before_action :require_authentication, **options
    end
  end

  private
    def resume_session
      Current.session ||= find_session_by_cookie
    end

    def find_session_by_cookie
      Session.find_by(id: cookies.signed[:session_id]) if cookies.signed[:session_id]
    end

    def start_new_session_for(user)
      user.sessions.create!(user_agent: request.user_agent, ip_address: request.remote_ip).tap do |session|
        Current.session = session
        cookies.signed.permanent[:session_id] = { value: session.id, httponly: true, same_site: :lax }
      end
    end
    # ...
end

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  include Authentication
  # ...
end

The line that matters most here is before_action :require_authentication — included into ApplicationController itself, which means every controller in the app requires a signed-in user by default, unless it explicitly opts out with allow_unauthenticated_access. This is the opposite of how most tutorials build auth (where you protect specific actions), and it’s a deliberate, sensible default for an app whose whole point is accounts: it’s much safer to have to remember to make a page public than to have to remember to protect it.

The signed cookie itself is worth reading closely too: cookies.signed.permanent[...] — signed, so the value can’t be forged (Rails verifies it against a secret before trusting it); permanent, so it’s set to expire 20 years out rather than at the end of the browser session; httponly: true, so client-side JavaScript can never read it (closing off a whole category of session-theft via XSS); same_site: :lax, a baseline CSRF protection that stops the cookie from being sent on cross-site requests except top-level navigation.

A gotcha: our public landing page just broke

Because require_authentication is now the default everywhere, episode 1’s landing page — meant to be the first thing anyone sees, logged in or not — would redirect to the sign-in page the moment we ran the generator. PagesController needed an explicit opt-out:

# app/controllers/pages_controller.rb
class PagesController < ApplicationController
  allow_unauthenticated_access

  def home
  end
end

This is exactly the trade-off “secure by default” makes on purpose: you will hit this the first time you add the generator to an app with existing public pages, and the fix is one line, but you have to know to look for it.

Signing in: authenticate_by and rate limiting

# app/controllers/sessions_controller.rb
class SessionsController < ApplicationController
  allow_unauthenticated_access only: %i[ new create ]
  rate_limit to: 10, within: 3.minutes, only: :create, with: -> { redirect_to new_session_path, alert: "Try again later." }

  def create
    if user = User.authenticate_by(params.permit(:email_address, :password))
      start_new_session_for user
      redirect_to after_authentication_url
    else
      redirect_to new_session_path, alert: "Try another email address or password."
    end
  end
  # ...
end

Two details here are genuinely worth understanding, not just copying.

User.authenticate_by looks like it’s just find_by(email_address:) + authenticate(password) in one call, but it’s specifically designed to close a timing attack. Straight from the Rails source comment:

Regardless of whether a record is found, authenticate_by will cryptographically digest the given password attributes. This behavior helps mitigate timing-based enumeration attacks, wherein an attacker can determine if a passworded record exists even without knowing the password.

Concretely: if you looked up the user first and only ran the bcrypt comparison when one was found, a request for a nonexistent email would return almost instantly (no bcrypt work), while a request for a real email with the wrong password would take the ~100ms bcrypt takes. That timing difference is enough for an attacker to enumerate which emails have accounts, purely by measuring response times. authenticate_by always does the expensive digest work, found or not, so both cases take the same time.

rate_limit is a native Rails 8 feature (ActionController::RateLimiting, no gem) — ten attempts per three minutes on this action, backed by Rails.cache, redirecting with a message instead of just failing silently. Brute-forcing a password by trying thousands of combinations is meaningfully slowed down by this one line.

The missing piece: sign-up

Try the generator’s routes and you’ll find new_session_path and new_password_path (reset), but nothing to create a User in the first place. That’s not an oversight — the generator can’t guess your app’s sign-up requirements (invite-only? email confirmation? OAuth?) so it leaves that entirely to you.

For VicinoTe, anyone should be able to sign up — it’s a marketplace, not an admin tool — so we add it ourselves, following the same shape as the generated code:

# app/controllers/registrations_controller.rb
class RegistrationsController < ApplicationController
  allow_unauthenticated_access

  def new
    @user = User.new
  end

  def create
    @user = User.new(user_params)

    if @user.save
      start_new_session_for @user
      redirect_to root_path, notice: "Welcome to VicinoTe!"
    else
      render :new, status: :unprocessable_entity
    end
  end

  private

  def user_params
    params.require(:user).permit(:email_address, :password, :password_confirmation)
  end
end

# config/routes.rb
resource :registration, only: [:new, :create]

Nothing here is new machinery — start_new_session_for is the same private method SessionsController uses, callable because it’s defined in the Authentication concern that’s mixed into every controller. Sign-up, in this design, is just “create a User, then do exactly what signing in does.”

Password reset without a reset-token column

This is the detail I found most worth digging into. PasswordsController calls User.find_by_password_reset_token!(token) — a method that doesn’t exist anywhere in user.rb. It isn’t hand-written, and there’s no reset_password_token column in the users table either. So where does it come from?

It comes from has_secure_password itself. Reading the Rails source (ActiveModel::SecurePassword):

def has_secure_password(attribute = :password, validations: true, reset_token: true)
  # ...
  if reset_token && respond_to?(:generates_token_for)
    generates_token_for :"#{attribute}_reset", expires_in: 15.minutes do
      public_send(:"#{attribute}_salt")&.last(10)
    end
    # defines find_by_password_reset_token / find_by_password_reset_token!
  end
end

generates_token_for is Rails’ general-purpose mechanism for generating a verifiable, expiring token without storing it anywhere — it’s a signed, encoded payload (via ActiveSupport::MessageVerifier), checked and decoded on the way back in. Here, has_secure_password uses it automatically, keyed off the last 10 characters of the password’s bcrypt salt.

That detail is the clever part: the salt changes every time the password changes (bcrypt generates a fresh one on every hash), which means a reset link is automatically invalidated the instant the password it was generated for actually changes — with no extra “used” flag, no token cleanup job, nothing to store. The token expires after 15 minutes either way, and find_by_password_reset_token! raises ActiveSupport::MessageVerifier::InvalidSignature on an expired or tampered token, which PasswordsController rescues into a friendly redirect.

We’re not building the full flow out today (that needs a real mailer setup, which will make more sense once VicinoTe is deployed somewhere), but it’s worth knowing this exists, fully wired, the moment has_secure_password is on the model — one line, and a working, secure password-reset mechanism came with it.

A small nav bar, so any of this is reachable

None of the above has a UI to get to unless something links to it, so the layout gets a minimal header:

<% if authenticated? %>
  <span><%= Current.user.email_address %></span>
  <%= button_to "Sign out", session_path, method: :delete %>
<% else %>
  <%= link_to "Sign in", new_session_path %>
  <%= link_to "Sign up", new_registration_path %>
<% end %>

authenticated? is the helper_method the Authentication concern exposes — it’s just resume_session, reused to answer “is anyone signed in” without redirecting.

Trying it

bin/dev

Sign up with any email and password — you land back on the homepage, already signed in, your email in the top bar. Sign out, then sign back in; try a wrong password and you’ll get the friendly error rather than a stack trace. None of this touches Service or Booking yet — the point of this episode is that accounts work, end to end, before anything gets built on top of them.

What’s next

Episode 3 builds Service and Category, and finally wires up the has_many :services association from episode 1’s design — the moment a signed-in user can actually list something they offer.

The scope here is deliberately narrow. No CRM, no campaigns, no message templates, no statistics — that’s the real project, and it isn’t what this series is about. This series is about one thing: getting a real WhatsApp message sent from a Rails app, understanding what’s actually happening when you do. We’ll build it two ways — through Twilio (this episode and the next), and then, as a separate episode, calling Meta’s WhatsApp Cloud API directly, without Twilio in between, so the two approaches can be compared.

Code is on GitHub, tagged episode-1, in the whatsapp-with-rails repo.

What we’re building, and why Twilio first

Before writing any code, it’s worth knowing what Twilio actually is here, because “WhatsApp API” is a slightly confusing phrase — there are two ways to get at it.

Meta owns WhatsApp, and Meta does offer a direct API (the WhatsApp Business Cloud API) to send and receive messages programmatically. You can integrate with it directly. But Meta’s API requires a Meta Business account, app review, phone number registration through Meta’s own system, and its authentication and webhook setup are Meta-specific.

Twilio sits on top of that. It’s a communications platform that already has the Meta integration done, wrapped in a simpler, well-documented REST API (and a Ruby gem) that looks and feels the same whether you’re sending WhatsApp, SMS, or a voice call. You still need WhatsApp-approved sender registration either way, but Twilio’s sandbox mode lets you start sending test messages in minutes, with no waiting on Meta’s approval process.

That’s why episode 1 and 2 use Twilio: it’s the fastest path to a real message actually arriving on a phone, and it’s genuinely a legitimate production choice, not just a shortcut — plenty of real products run their WhatsApp messaging through Twilio permanently. Episode 3 then does the same job through Meta’s API directly, so the trade-off (simplicity and speed vs. one less service in the middle) is visible in actual code, not just in the abstract.

Creating the app

rails new whatsapp-with-rails -d postgresql --css tailwind

Same reasoning as the other series on this blog: PostgreSQL because it’s a reasonable default for anything that might grow, Tailwind to keep the views readable without a separate stylesheet. Nothing here is Twilio-specific yet — this command is identical to how you’d start any small Rails app.

bin/rails db:create

The Contact model

The real project has a full CRM — segments, tags, GDPR consent tracking, import/export. Here we need exactly two fields: who, and what number to message.

bin/rails generate model Contact name:string whatsapp_number:string

Two things worth doing before migrating: making both fields required, and validating the phone number format properly — because WhatsApp messaging requires a specific number format, and it’s much better to catch a malformed number in a form validation than in a failed API call later.

# db/migrate/..._create_contacts.rb
create_table :contacts do |t|
  t.string :name, null: false
  t.string :whatsapp_number, null: false

  t.timestamps
end

# app/models/contact.rb
class Contact < ApplicationRecord
  validates :name, presence: true
  validates :whatsapp_number, presence: true, format: {
    with: /\A\+[1-9]\d{6,14}\z/,
    message: "must be in E.164 format, e.g. +391234567890"
  }
end

Why E.164, specifically

E.164 is the ITU’s international standard for phone number formatting — the format that guarantees a number is unambiguous anywhere in the world. The shape is + followed by the country calling code, followed by the subscriber number, no spaces, no dashes, no parentheses, no leading zero on the local part where the country’s dialing plan would normally have one.

A concrete example: an Italian mobile number you’d normally write as 333 1234567 becomes +393331234567 in E.164 — country code 39, then the number as-is (Italian mobile numbers don’t carry a leading trunk zero to begin with).

Why this matters here specifically: Twilio’s WhatsApp API — and the underlying WhatsApp protocol itself — requires E.164. Without a single unambiguous format, 333-1234567 is meaningless out of context: is it missing a country code? Does it need a leading zero stripped? E.164 removes every one of those questions.

The regex mirrors the standard directly: +, then a digit 1–9 (country codes never start with 0), then 6 to 14 more digits — matching E.164’s actual hard limit of 15 digits total after the +.

bin/rails db:migrate

Routes, controller, contacts list

Just enough REST to list contacts and add one — no edit, no delete, not needed for this demo:

# config/routes.rb
resources :contacts, only: [:index, :new, :create]
root "contacts#index"

# app/controllers/contacts_controller.rb
class ContactsController < ApplicationController
  def index
    @contacts = Contact.order(:name)
  end

  def new
    @contact = Contact.new
  end

  def create
    @contact = Contact.new(contact_params)

    if @contact.save
      redirect_to contacts_path, notice: "Contact added."
    else
      render :new, status: :unprocessable_entity
    end
  end

  private

  def contact_params
    params.require(:contact).permit(:name, :whatsapp_number)
  end
end

Two things worth calling out, both carried over from lessons in earlier series on this blog: create redirects after a successful save (the Post/Redirect/Get pattern — see episode 3 of AI with Ruby for why that specifically matters for Turbo Drive), and a failed save renders with status: :unprocessable_entity rather than the default 200 OK — the correct HTTP status for “the request was understood but the data was invalid,” and something Turbo itself checks for when deciding whether to treat a form response as an error.

The views are a plain list and a plain form — nothing new here, so I won’t repeat them in full; they’re in the repo if you want to see the Tailwind markup.

Trying it

bin/dev

Open http://127.0.0.1:3000: an empty contacts list, an “Add contact” button, a form. Try submitting a number without the + — the validation catches it, with the exact error message explaining what’s expected.

Nothing here talks to Twilio yet. That’s deliberate — episode 2 wires in the twilio-ruby gem and actually sends a message to one of these contacts.

What’s next

Episode 2 adds the twilio-ruby gem, a form to compose a message, and the API call that sends it — plus what a Twilio WhatsApp sandbox actually is and why you need one before Meta approves your own sender.

Every episode comes with exercises in a companion repo: ruby-deep-dive, tagged episode-1. Each one is a method stub to fill in, checked by a test. Read the episode, then go make the tests pass yourself — the exercises are deliberately left unsolved in the repo, because doing them is the point.

We’re starting at the real beginning: what a variable is, and Ruby’s basic types.

What a variable actually is

language = "Ruby"

This line does two things: it creates a String object holding the text "Ruby", and it makes the name language point to it. That’s worth being precise about, because “variable” can be a misleading word if you’re coming from a language where variables are boxes that hold values directly. In Ruby, a variable is a label, and what it labels is an object living somewhere in memory. Two variables can point to the very same object:

a = "Ruby"
b = a
b.upcase!
a #=> "RUBY"

Changing b changed a too, because they were never two separate strings — they were two labels on the same one. upcase! (with the !) mutates the string in place, rather than returning a new one. This distinction — is a variable a label or a box — is the root of a lot of confusion later on with method arguments and mutation, so it’s worth having clearly in mind from episode 1.

Ruby doesn’t require you to declare a variable’s type. language isn’t “a string variable” — it’s just a name currently pointing at a String. Assign it something else, and it points at that instead:

language = "Ruby"
language = 42

Both lines are completely legal, one after the other. The variable didn’t change type — it just points somewhere new.

Local variable naming

A local variable name starts with a lowercase letter or an underscore, and by convention uses snake_case:

favorite_language = "Ruby"
_unused = "starts with an underscore, often used to mark 'I know I'm not using this'"

Ruby cares about this convention more than most languages: CamelCase names are reserved for constants and class/module names, so FavoriteLanguage = "Ruby" doesn’t create a local variable — it creates a constant, a different kind of thing entirely, one Ruby will warn you about if you reassign it.

The basic types

String

Text, in double or single quotes. The difference matters: double-quoted strings support interpolation and escape sequences, single-quoted ones don’t.

name = "Antonino"
"Hello, #{name}!"   #=> "Hello, Antonino!"
'Hello, #{name}!'   #=> "Hello, #{name}!" (literally, no interpolation)

Interpolation — #{...} inside a double-quoted string — evaluates whatever Ruby expression is inside the braces and inserts its string form. It’s the idiomatic way to build strings in Ruby; reach for it instead of + concatenation.

Symbol

:ruby

A Symbol looks like a string with a colon in front, and it’s tempting to think of it as “a string that can’t change.” That’s close, but the more useful way to think about it: a Symbol is a name, used as an identifier, not as data to display or manipulate. The same symbol written twice is always the exact same object in memory:

:ruby.object_id == :ruby.object_id  #=> true
"ruby".object_id == "ruby".object_id #=> false

That’s why symbols show up constantly as hash keys and method names in Ruby code — they’re cheap to compare (Ruby just checks if it’s the same object, not character-by-character) and cheap to store (no duplicate copies). The rule of thumb: if the value is something a human will read on screen, it’s probably a String. If it’s an internal label the program uses to refer to something, it’s probably a Symbol.

Integer and Float

42        # Integer
3.14      # Float

One thing that surprises people coming from other languages: integer division truncates, it doesn’t round or raise an error.

7 / 2     #=> 3, not 3.5
7 / 2.0   #=> 3.5
7.0 / 2   #=> 3.5

If either operand is a Float, the result is a Float. If both are Integer, you get integer division. This is exactly why add_as_float in this episode’s exercises asks you to convert before adding — 2 + 3 is 5, an Integer, no matter how you write the method.

nil, true, and false

nil represents the absence of a value — not zero, not an empty string, genuinely nothing. true and false are the only two values of a separate type, TrueClass and FalseClass respectively (yes, true and false are each the sole instance of their own class — more on why that’s not as strange as it sounds when we get to “everything is an object” in episode 5).

Here’s the detail that trips up almost everyone arriving from another language: in Ruby, only nil and false are falsy. Everything else is truthy — including 0, including "" (empty string), including empty arrays and hashes.

if 0
  puts "this runs"   # it does! 0 is truthy in Ruby
end

if ""
  puts "so does this"  # also runs
end

Coming from JavaScript, Python, or PHP, where 0 and "" are falsy, this is the single most common source of “why did my if do that” confusion. Keep it in mind and it’ll stop surprising you fast.

The exercises

Head to 01-variables-and-basic-types/exercises.rb in the repo. Seven methods, all empty, all covering something from this post: assignment, interpolation, string-to-integer conversion, symbols, nil checking, forcing a Float result, and — deliberately — finding “the other falsy value” without it being named for you directly in the exercise.

git clone https://github.com/AntoninoScaffidi/ruby-deep-dive.git
cd ruby-deep-dive
bundle install
ruby 01-variables-and-basic-types/exercises_test.rb

Every test will fail until you fill in the corresponding method. That’s the intended starting state — turn them green one at a time.

What’s next

Episode 2 covers control flow: if/unless/case, loops, and a closer look at truthy/falsy now that the basic types are in place.

This episode fixes that. By the end, conversations survive a page refresh, live in the database, and the model actually remembers what was said earlier in the same conversation — because we’re sending it the real history, not just the latest message.

The code is tagged episode-3 in the ai-with-ruby-demo repo.

Two ways to persist a chat

You could write Conversation and Message models by hand: a has_many/belongs_to pair, a controller that appends to an array of messages, some JSON serialization to store what the model said. It would work, but you’d be rebuilding something RubyLLM already ships as a first-class Rails integration, complete with a generator, migrations, and the acts_as_chat / acts_as_message pattern you’ll see in RubyLLM’s own documentation and examples.

We’re using the generator. Not because doing it by hand is wrong, but because the generated code is the idiomatic way to use this gem in Rails — reading it is as instructive as writing it yourself, and you end up with code that matches what you’ll find in RubyLLM’s docs and in other people’s projects.

Running the generator

bin/rails generate ruby_llm:install chat:Conversation --skip-active-storage

Two things are non-default here, so let’s be explicit about both.

chat:Conversation. Left alone, the generator names the model that represents a chat session Chat. That’s a reasonable default, but “conversation” is the word we’ll actually use when we talk about this feature, so we tell the generator to call it Conversation instead. The generator’s own usage line spells out the syntax: bin/rails g ruby_llm:install [chat:ChatName] [message:MessageName] ... — you can rename any of the models it creates the same way.

--skip-active-storage. By default the generator also runs active_storage:install and adds has_many_attached :attachments to the message model, so a chat can have file uploads attached to it. We’re not building file attachments in this episode, so we skip it. Nothing stops you from adding it later — the flag only skips it now.

What the generator actually creates

This is worth going through file by file, because it creates more than a Conversation and a Message — and it’s better to know why than to have unexplained files sitting in the app.

create  db/migrate/..._create_conversations.rb
create  db/migrate/..._create_messages.rb
create  db/migrate/..._create_tool_calls.rb
create  db/migrate/..._create_models.rb
create  db/migrate/..._add_references_to_conversations_tool_calls_and_messages.rb
create  app/models/conversation.rb
create  app/models/message.rb
create  app/models/tool_call.rb
create  app/models/model.rb
force   config/initializers/ruby_llm.rb
create  app/agents/.gitkeep
create  app/tools/.gitkeep
create  app/schemas/.gitkeep
create  app/prompts/.gitkeep

conversations table. Just an empty shell plus timestamps — a conversation on its own doesn’t need to store anything, it just groups messages together. A model_id reference gets added later by the fifth migration, recording which LLM model that conversation is using.

messages table. This is where the substance lives: role ("user", "assistant", or "system"), content, and content_raw (a JSON column holding the full raw structure, needed for messages that aren’t plain text — like tool calls). There are also columns for extended thinking (thinking_text, thinking_signature, thinking_tokens — for models that expose their reasoning process) and token accounting (input_tokens, output_tokens, cached_tokens, cache_creation_tokens). We won’t touch the thinking or token columns in this episode, but it’s worth knowing they’re there: this same table is built to support features several episodes away.

tool_calls table. Not used yet — this is for a later episode on tool calling, when the model will be able to call into our own application code. The table stores which tool was called (name), with what (arguments, as JSON), and links back to the message that triggered it.

models table. A local cache of model metadata — pricing, context window size, which capabilities a given model supports. It’s populated by a separate rake task (bin/rails ruby_llm:load_models) that we’re not running in this episode, since nothing here depends on it yet. The model_id reference added to conversations and messages is optional (foreign_key: true, no null: false), so everything works fine without it.

The generated models:

# app/models/conversation.rb
class Conversation < ApplicationRecord
  acts_as_chat
end

# app/models/message.rb
class Message < ApplicationRecord
  acts_as_message chat: :conversation
end

acts_as_chat and acts_as_message are class methods RubyLLM adds to ActiveRecord::Base. They set up the has_many/belongs_to association between the two models and mix in the methods that make a Conversation behave like a RubyLLM chat session — most importantly, .ask. Because we renamed the model to Conversation, acts_as_message needed to know the association isn’t called chat anymore, hence chat: :conversation. The generator worked this out on its own from the chat:Conversation mapping we passed it.

The convention directories (app/agents, app/tools, app/schemas, app/prompts, each with just a .gitkeep for now) are empty scaffolding for features later in this series — tools an agent can call, structured output schemas, reusable prompts. Nothing goes in them yet.

A gotcha: the deprecated legacy API

Here’s something that isn’t obvious from the README alone, and that we ran into directly. RubyLLM ships two implementations of the ActiveRecord integration: the current one (what we just described) and a legacy one, kept only for backward compatibility. Which one loads is controlled by a config flag, use_new_acts_as.

Without it, RubyLLM silently loads the legacy implementation and prints this at boot:

!!! RubyLLM's legacy acts_as API is deprecated and will be removed in RubyLLM 2.0.0.
Please consult the migration guide at https://rubyllm.com/upgrading-to-1-7/

This is exactly the warning we saw back in episode 2, before we’d even touched persistence — it’s printed at boot as soon as ActiveRecord loads, regardless of whether you’re using acts_as_chat yet. The generator knows about this and sets the flag correctly on its own:

# config/initializers/ruby_llm.rb
RubyLLM.configure do |config|
  config.openai_api_key = ENV.fetch("OPENAI_API_KEY", nil)

  # Use the current, association-based acts_as API. Without this, RubyLLM
  # silently falls back to a deprecated implementation and warns about it.
  config.use_new_acts_as = true
end

If you ever add RubyLLM’s ActiveRecord integration to a project without using the generator, this is the one line most worth copying by hand — it’s easy to miss, and the two implementations aren’t identical, so code written against one doesn’t necessarily work against the other.

Running the migrations

bin/rails db:migrate

This creates all four tables described above, plus the fifth migration that wires up the foreign keys between them.

Trying it from the console, before touching the controller

Worth doing once, to see persistence working with nothing else in the way:

bin/rails runner '
conversation = Conversation.create!
response = conversation.ask "Reply with exactly one word: pong"
puts "RESPONSE: #{response.content}"
puts "MESSAGES IN DB: #{conversation.messages.count}"
puts "ROLES: #{conversation.messages.pluck(:role).join(%q{, })}"
'

RESPONSE: pong
MESSAGES IN DB: 2
ROLES: user, assistant

One .ask call, two rows written: the user’s message and the model’s reply, both persisted automatically. No deprecation warning either — the flag is doing its job.

Wiring it into the controller

Episode 2’s controller created a fresh, throwaway chat on every request. Now we need to find the same conversation across requests. For a single-user demo with no accounts yet, the simplest thing that’s still correct is to keep the conversation’s id in the Rails session — a small, signed cookie tied to the visitor’s browser.

# app/controllers/chats_controller.rb
class ChatsController < ApplicationController
  def new
    @conversation = current_conversation
  end

  def create
    current_conversation.ask(params[:message])
    redirect_to new_chat_path
  end

  private

  def current_conversation
    Conversation.find_by(id: session[:conversation_id]) || create_conversation
  end

  def create_conversation
    conversation = Conversation.create!
    session[:conversation_id] = conversation.id
    conversation
  end
end

current_conversation looks up the conversation by the id stored in the session; if there isn’t one yet (first visit, or the session expired), it creates one and remembers its id for next time. create no longer renders anything itself — it asks the question, then redirects back to new, which is now responsible for loading and displaying the conversation, messages included.

Showing the history

<div class="max-w-xl mx-auto mt-16 px-4">
  <h1 class="text-2xl font-semibold mb-6">RubyLLM chat demo</h1>

  <div class="space-y-4 mb-8">
    <% @conversation.messages.each do |message| %>
      <% is_user = message.role == "user" %>
      <div class="<%= is_user ? "text-right" : "text-left" %>">
        <p class="text-xs text-gray-500 mb-1"><%= message.role %></p>
        <p class="inline-block rounded-md px-3 py-2 <%= is_user ? "bg-indigo-600 text-white" : "bg-gray-100" %>">
          <%= message.content %>
        </p>
      </div>
    <% end %>
  </div>

  <%= form_with url: chat_path, method: :post, class: "flex flex-col gap-3" do %>
    <textarea name="message" rows="3" placeholder="Ask something..."
      class="border border-gray-300 rounded-md p-3 focus:outline-none focus:ring-2 focus:ring-indigo-500"></textarea>
    <button type="submit" class="self-start bg-indigo-600 text-white px-4 py-2 rounded-md hover:bg-indigo-700">
      Send
    </button>
  <% end %>
</div>

@conversation.messages comes for free from acts_as_chat — it’s the has_many association, already ordered oldest-first. We loop over it, and use message.role (a plain string column: "user" or "assistant") to align and colour each bubble differently. There’s no helper method like message.user? — the role is just a string, so a direct comparison is all we need.

Closing episode 2’s open thread: Turbo Drive works again

Episode 2 ended with data: { turbo: false } on the form, as a workaround: Turbo Drive intercepted the submission and expected either a Turbo Stream response or a redirect, and our controller was doing neither — it rendered plain HTML, which Turbo didn’t know how to handle, so the page silently failed to update.

Look at this episode’s create action again: it doesn’t render anything, it redirects. That’s the Post/Redirect/Get pattern — after a form submission that changes something, redirect to a page that shows the result, rather than rendering a result directly from the POST action. It’s good practice on its own (it stops a page refresh from re-submitting the form), and it also happens to be exactly what Turbo Drive expects. So the workaround is gone — the form in this episode has no data: { turbo: false } at all, and it works.

This is worth sitting with for a second: the fix in episode 2 wasn’t wrong, but it was treating a symptom. The real fix was adopting the pattern Rails (and Turbo) are built around in the first place.

Trying it in the browser

bin/dev

Open http://127.0.0.1:3000, ask something, and the reply appears below the form. Refresh the page — the conversation is still there. Ask a follow-up that depends on the first message (“what did I just ask you?”) and the model answers correctly, because the full history is sent with every request, not just the latest line.

What’s next

Episode 4 covers streaming responses: instead of waiting for the full reply before showing anything, we’ll stream it in as the model generates it, using Turbo Streams properly this time.

The name comes from the Italian vicino a te, “close to you”. VicinoTe is a marketplace for local services: you find someone nearby to fix a tap, teach guitar, walk a dog or renovate a bathroom — or you offer your own skills to the people around you.

In this episode we set up the project and, more importantly, decide what we’re actually building. The code is on GitHub, tagged episode-1 in the vicinote-tutorial repo, which will grow with every post.

Why a marketplace

Tutorials often build a blog or a to-do list. Those are fine for learning syntax, but they’re too simple to run into the problems that make Rails interesting: the same record playing different roles depending on context, money, availability, permissions, search that has to actually be good.

A services marketplace hits all of them, and it does so gradually — you can have something working after two episodes and still have plenty left to build after ten.

Creating the app

rails new vicinote-tutorial -d postgresql --css tailwind

Three decisions are baked into that line, so let’s be explicit about them.

-d postgresql. Rails 8 defaults to SQLite, which is genuinely a good default now. I’m choosing PostgreSQL anyway for one specific reason: the AI episodes later in this series need vector search to power semantic search over services. The standard way to do that in Postgres is the pgvector extension, and having it available without migrating the database mid-series is worth the small extra setup now.

--css tailwind. Personal preference, and it keeps the views readable without a separate stylesheet to maintain alongside the tutorial. Nothing in the series depends on Tailwind specifically — if you prefer plain CSS, the markup will still make sense.

Rails 8 defaults we’re keeping. The generator also brings in Propshaft, Importmap, Turbo, Stimulus, and the Solid trio (Solid Queue, Solid Cache, Solid Cable). We’re not configuring any of them yet, but they’re the reason there’s no Redis and no Node build step in this project.

Then create the databases:

bin/rails db:create

If that command fails, PostgreSQL isn’t running or isn’t reachable — that’s the one piece of setup you have to sort out on your own machine before continuing.

Designing the domain

This is the part worth slowing down on. Getting the model right now saves a lot of painful migrations later.

Here’s the shape we’re aiming for:

User            can offer services AND book them
 ├─ Service     something a user offers (title, description, price)
 │   └─ Category
 └─ Booking     a user books another user's service
     └─ Review  left after the booking is completed

The important decision: one User, two roles

The central question in any marketplace is how to represent the two sides of the transaction. There are three common answers.

Option A — separate models. A Provider model and a Customer model, each with its own table.

This is the first idea most people have, and it’s usually wrong. You immediately duplicate everything that isn’t role-specific: email, password digest, name, avatar, phone number, address. Then you need authentication that works for both, which means either two login flows or a polymorphic mess. And the moment someone who offers guitar lessons wants to book a plumber, they need two accounts with two passwords — which is absurd, and exactly the situation a neighbourhood marketplace runs into constantly.

Option B — a role column on User. One users table with role: "provider" or role: "customer".

Better, but it encodes a false assumption: that being a provider or a customer is a permanent property of a person. It isn’t. It’s a property of a particular relationship. The same person is a provider in the booking where they teach guitar and a customer in the booking where they hire a plumber. A single role column can’t express that, and you’ll end up fighting it.

Option C — role emerges from the association. One User model, no role column. You’re a provider of the services you created, and a customer of the bookings you made.

This is what we’ll use:

class User < ApplicationRecord
  has_many :services                                        # things I offer
  has_many :bookings, foreign_key: :customer_id             # things I booked
  has_many :received_bookings, through: :services, source: :bookings
end

No duplication, one login, and a user who does both is the normal case rather than an edge case. When we later need “provider-only” behaviour, it’s a question about the data (user.services.any?), not about a flag we have to keep in sync.

To be fair about the trade-off: this approach makes some queries slightly more involved. “Show me everything happening in my account” has to look at two associations instead of one. In exchange, we never have to answer “what happens when a customer becomes a provider” — because nothing does. That’s a good deal.

Bookings hold the money

A Booking isn’t just a link between a user and a service. It’s the record of an agreement at a point in time: the date, the agreed price, the status. It needs its own price column rather than reading service.price, because the service’s price can change tomorrow and that must not silently rewrite what someone agreed to pay last week.

This kind of thing is easy to get wrong and painful to fix once real data exists, which is why we’re deciding it before writing a single migration.

Reviews belong to bookings, not to services

It’s tempting to attach a Review directly to a Service. Attaching it to a Booking instead gives us something valuable for free: only someone who actually booked and completed a service can review it. The constraint is built into the shape of the data rather than enforced by validation logic we have to remember to write.

A landing page

To finish with something visible, a static home page:

bin/rails generate controller Pages home --skip-routes --no-helper --no-assets

# config/routes.rb
root "pages#home"

I used --skip-routes because the generator would otherwise add get "pages/home", and we want this at the root instead. --no-helper and --no-assets just avoid creating files we won’t use.

The view itself is plain markup describing the project, with two buttons deliberately left inert — placeholders for the flows we build next.

bin/dev

Open http://127.0.0.1:3000 and there it is: an empty app that knows what it wants to become.

What’s next

Episode 2 turns the domain sketch into real code: the User model, authentication, and the first migrations. From there the marketplace starts taking shape — services, categories, and the flows that connect the two sides of a booking.

The full code for this episode is on GitHub, tagged episode-2, in a new companion repo — ai-with-ruby-demo — that will grow with each post in this series.

Setting up the app

A fresh Rails 8 app with Tailwind CSS:

rails new ai-with-ruby-demo --css tailwind

Two gems go in the Gemfile:

gem "ruby_llm"

group :development do
  gem "dotenv-rails"
end

ruby_llm is the library itself. dotenv-rails loads a .env file into ENV in development — Rails doesn’t do this on its own.

Keeping the API key out of git

Rails 8’s default .gitignore already excludes .env*, so a .env file with your real key never gets committed. We commit an .env.example instead, as a template for anyone cloning the repo:

OPENAI_API_KEY=sk-your-key-here

Copy it locally and fill in your real key:

cp .env.example .env

Configuring RubyLLM

Files in config/initializers/ run once, at boot, before any request is handled — the right place to configure a gem like this:

# config/initializers/ruby_llm.rb
RubyLLM.configure do |config|
  config.openai_api_key = ENV.fetch("OPENAI_API_KEY", nil)
end

Routes and controller

A resource (singular) fits here — there’s no list of chats to index or a specific one to fetch by ID, just a single form:

# config/routes.rb
resource :chat, only: [:new, :create]
root "chats#new"

# app/controllers/chats_controller.rb
class ChatsController < ApplicationController
  def new
  end

  def create
    @message = params[:message]
    chat = RubyLLM.chat
    @response = chat.ask(@message).content
    render :new
  end
end

RubyLLM.chat creates a new, in-memory chat session — nothing persisted anywhere, which is exactly why the conversation disappears on refresh right now. .ask sends the message and blocks until the model replies; .content is the reply text.

The view

<%= form_with url: chat_path, method: :post, data: { turbo: false } do %>
  <textarea name="message"><%= @message %></textarea>
  <button type="submit">Send</button>
<% end %>

<% if @response %>
  <p><%= @response %></p>
<% end %>

The Turbo gotcha

The first version of this form didn’t have data: { turbo: false }, and submitting it did… nothing visible. The server logs showed a clean 200 OK, but the page never updated.

The cause: Rails 8 ships with Turbo Drive by default, which intercepts every form submission and sends it as a background request, expecting either a redirect or a response in the Turbo Stream format. Our controller just rendered plain HTML — Turbo received it but didn’t know what to do with it, so it silently did nothing.

data: { turbo: false } tells Turbo to leave this specific form alone and submit it the old-fashioned way: a real page load. That’s the right fix for now. When we get to streaming responses later in this series, we’ll actually want Turbo Streams — but for a first “does this work at all” version, disabling it is the simplest path.

What’s next

Episode 3 adds persistence: Conversation and Message models, so the chat history survives a page refresh instead of living only inside a single request.

RubyLLM changes that. It’s a gem that gives you a clean, idiomatic Ruby interface to large language models — OpenAI, Anthropic, Gemini, and others — without forcing you to hand-roll HTTP requests and JSON parsing every time you want to talk to a model.

This post kicks off a new series on this blog where we’ll explore AI in the context of Ruby and Rails applications. We’ll start simple and build up to more advanced patterns: streaming responses, tool calling, and semantic search over your own data. This first episode is just about getting RubyLLM installed and making your first call.

Why RubyLLM

A few things make RubyLLM a good fit for Rails apps specifically:

• One interface, many providers. You configure a provider and model once, and the calling code doesn’t need to change if you switch from, say, GPT-4 to Claude.
• Rails-friendly. It plays well with ActiveJob, ActiveRecord, and the conventions you already know, instead of asking you to adopt a separate framework.
• No boilerplate. No manual JSON building, no manually parsing streaming chunks — the gem handles that.

Installation

Add the gem to your Gemfile:

gem "ruby_llm"

Then install it:

bundle install

Configuration

RubyLLM needs at least one API key to talk to a provider. A common approach is an initializer:

# config/initializers/ruby_llm.rb
RubyLLM.configure do |config|
  config.openai_api_key = ENV["OPENAI_API_KEY"]
end

Keep the actual key out of source control — use Rails credentials or an environment variable loaded via a .env file in development.

Your First Call

With configuration in place, talking to a model is a single method call:

chat = RubyLLM.chat
response = chat.ask "What's a good name for a Ruby gem that talks to LLMs?"

puts response.content

RubyLLM.chat gives you a chat session you can keep asking questions in, and it keeps track of the conversation history for you — so a follow-up question like “What about a shorter one?” will still have the earlier context.

What’s Next

In the next episode of this series, we’ll wire RubyLLM into a real Rails app and build a simple chatbot backed by ActiveRecord-stored conversation history. Later episodes will cover semantic search and tool calling — letting the model call into your own application code to fetch data or take actions.

This blog will soon kick off a new series called VicinoTe — a from-scratch Rails tutorial building a local services marketplace. This AI series will eventually connect back to it: VicinoTe’s advanced module will use RubyLLM for exactly the features described above.