The problem is that gathering data from social networks is grunt work. Open Instagram, YouTube, X, look at numbers, compare to competitors, check the events calendar, monitor sponsors, read comments, calculate engagement, decide how much to charge for a sponsored post. All manual, all repetitive, all eating time that should go to creating content.

I did what any programmer boyfriend would do: I built a full data mining system, with automated collection, LLM-driven analysis, and a Discord chatbot where she talks to the data in plain language.

This article isn’t about the code itself (the project won’t be open source). It’s about the build process, the decisions that only show up after you start, the technical tricks that saved the project, and why a wishlist document from your user is worth more than any functional spec.

Start with the Wish, Not the Architecture

The first thing I did was sit down with her and ask her to talk freely about what she wanted. No technical jargon, no form, no user stories. Her own words. I recorded it in an IDEA.md file that became the north star for the whole project.

What came out of it:

“My biggest difficulty today is figuring out what kind of content to make that can really take off and why the ones that worked actually worked, what made them get the result they got. I have to read the comments on the videos to get a general sense of why.”

“How much I should/could charge for a sponsored post, based on engagement research, competition, sponsors, events.”

“How to make a sponsored post that doesn’t look like a sponsored post — paid content that brings engagement without looking like just a sales pitch.”

She didn’t ask for a dashboard. She didn’t ask for charts. She didn’t ask for PDF reports. She asked for answers to concrete day-to-day problems. That completely changed how I approached the architecture.

If I had started from a technical spec, I’d have built an analytics platform with pretty charts and CSV exports. The system she actually needed was something more like an assistant that knows the data and answers questions in Portuguese.

The IDEA.md also listed initial competitors and sponsors. Brands she could work with (themed restaurants, figure shops, Crunchyroll, Piticas, Fanlab). Reference profiles on Instagram. All of it became seed data. The document wasn’t a spec — it was a conversation that turned into organic requirements.

58 Commits in 3 Days

The project was built in 3 days. Not 3 weeks, not 3 months. 58 commits, 3 distinct phases:

Day 1 — The Data Engine. 12 commits. Rails 8 scaffold, models, collectors for YouTube/Instagram/X, LLM integration. Discovery pipeline to find new profiles automatically. Per-post performance scoring. Sentiment analysis of comments via Claude. By the end of the day, the system was collecting data from all 3 platforms and classifying every post as viral, above average, average, below or flop.

Day 2 — The Brain and the Voice. 35 commits. The most intense day. Two big subsystems showed up: the “Oracle” (tracking events, conventions, game/movie/anime releases, news) and the Discord chatbot with tool calling via RubyLLM. Also production hardening, Docker, deploy guide. And a big pivot: I swapped the weekly email report for 5 daily Discord digests.

Day 3 — Entertainment and Resilience. 11 commits. Steam games (Store API + SteamSpy), AniList for tracking seasonal anime, growth analytics, image generation via Gemini, an auto-healing system for broken URLs.

The final numbers:

These numbers aren’t to my credit. Claude wrote a good chunk of the code. But the direction, the architectural decisions, and especially the validation of every step were human. Claude doesn’t know what a Brazilian cosplay influencer needs. Neither did I — but she told me.

The Architecture That Emerged

The final system is a headless Rails 8. Zero web interface. No views, no real controllers (just /up for the health check). All functionality is delivered via background jobs, rake tasks, and the Discord chatbot.

The stack:

• Rails 8.1 with Solid Queue (jobs) and Solid Cache
• SQLite3 in production (WAL mode, bind mount between containers)
• RubyLLM for integration with Claude Sonnet via OpenRouter and Grok
• Ferrum for scraping with headless Chrome
• Discordrb for the chatbot
• Docker Compose with 4 services

The docker-compose.yml ended up lean:

x-app: &app
  build: .
  env_file: .env
  restart: unless-stopped
  volumes:
    - ./data/storage:/rails/storage

services:
  app:
    <<: *app
    ports:
      - "127.0.0.1:3000:80"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/up"]
    deploy:
      resources:
        limits:
          memory: 512M

  jobs:
    <<: *app
    command: bundle exec rake solid_queue:start
    depends_on:
      app:
        condition: service_healthy
    deploy:
      resources:
        limits:
          memory: 1G

  discord:
    <<: *app
    command: bundle exec rake discord:start
    depends_on:
      app:
        condition: service_healthy

  chrome:
    image: chromedp/headless-shell:stable
    deploy:
      resources:
        limits:
          memory: 1G

4 containers: app (Puma, basically just the health check), jobs (Solid Queue running 25+ scheduled jobs), discord (the bot), and chrome (headless browser for scraping). All state lives in SQLite via a bind mount on the host. No Redis, no Postgres, no extra infrastructure.

Idempotency Above All

If I had to pick one concept to summarize this project, it would be idempotency. Every job can run twice in a row without creating duplicates, without corrupting data, without side effects.

The base pattern:

module Collection
  class BaseCollectorJob < ApplicationJob
    SNAPSHOT_DEDUP_WINDOW = 1.hour

    retry_on StandardError, wait: :polynomially_longer, attempts: 3

    def perform(profile_id: nil)
      scope = profile_id ? SocialProfile.where(id: profile_id) : profiles_to_collect
      scope.find_each do |profile|
        log = find_or_create_log(profile)
        begin
          items = collect_for_profile(profile)
          profile.touch(:last_collected_at)
          log.update!(status: :completed, items_collected: items || 0)
        rescue => e
          log.update!(status: :failed, error_message: "#{e.class}: #{e.message}")
          raise if should_raise?(e)
        end
      end
    end

    def upsert_post(profile, attrs)
      post = profile.social_posts.find_or_initialize_by(
        platform_post_id: attrs[:platform_post_id]
      )
      post.assign_attributes(attrs.except(:platform_post_id))
      post.save!
      post
    end

    def record_snapshot(profile, metrics)
      return if profile.profile_snapshots
        .where("captured_at > ?", SNAPSHOT_DEDUP_WINDOW.ago).exists?
      profile.profile_snapshots.create!(captured_at: Time.current, **metrics)
    end
  end
end

Two protection mechanisms: find_or_initialize_by(platform_post_id) for posts (upsert, not insert), and SNAPSHOT_DEDUP_WINDOW for snapshots (skip if we already collected one in the last hour). If the job crashes mid-run and Solid Queue requeues it, nothing duplicates.

Scraping errors (BlockedError, RateLimitError) get swallowed silently — retrying doesn’t help, the rate limit needs to cool off, and getting blocked is expected. Real errors (database, network, bugs) bubble up to the retry with polynomial backoff.

This decision to “swallow certain errors” feels wrong until you run the system for a week and see that Instagram blocks one in every 5 collection runs. If every block triggered 3 retries with exponential backoff, the system would be perpetually behind.

nil vs Zero

This is one of those conceptual bugs you only discover with real data. When Instagram doesn’t return the share count for a post (because the API simply doesn’t expose that field), should the value be nil or 0?

The difference matters. nil means “we don’t have this data”. Zero means “we have the data and it’s zero”. If you treat nil as zero, the LLM analysis concludes that nobody shares posts on Instagram — which is false. The API just doesn’t expose that metric.

I built a reusable prompt snippet just for this:

When a field is null: don’t say “0 likes” — say “data not available for this platform”. When comparing platforms, warn that certain metrics aren’t comparable. When it’s zero: report it normally — the data is real and confirmed by the API.

That snippet gets included in every prompt that handles numeric data. Without it, the LLM happily mixes “not collected” with “actually zero” and draws wrong conclusions.

The Headless Chrome Trick: Host Header Bypass

The project uses chromedp/headless-shell in a separate container for scraping. Works perfectly. Until you try to connect Ferrum (the Ruby Chrome automation gem) to it over Docker networking.

The problem: chromedp/headless-shell uses a socat proxy on port 9222 that rejects any request whose Host header isn’t localhost or an IP. When Ferrum tries to connect to http://chrome:9222, the Host header goes out as chrome:9222, and socat refuses.

The fix was to discover the WebSocket URL manually, forging the header:

def discover_ws_url(chrome_url)
  uri = URI.parse("#{chrome_url}/json/version")
  req = Net::HTTP::Get.new(uri)
  req["Host"] = "localhost"  # bypass

  response = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(req) }
  data = JSON.parse(response.body)

  ws_url = data["webSocketDebuggerUrl"]
  return nil unless ws_url

  # WS URL points to 127.0.0.1 inside the container — swap it for the reachable hostname
  remote_uri = URI.parse(chrome_url)
  ws_url.sub(%r{://[^/]+}, "://#{remote_uri.host}:#{remote_uri.port}")
end

I do the GET to /json/version with Host: localhost to slip past socat. I get the WebSocket URL back (which points at 127.0.0.1 — useless from outside the container). I rewrite the hostname to chrome:9222 (the service name in Docker Compose). I hand the ws_url straight to Ferrum, which opens the WebSocket without going through socat’s HTTP layer.

This kind of thing doesn’t come to mind upfront. You discover it after 1 hour of connection refused and reading the source code of chromedp/headless-shell.

Tool Calling: The Bot That Queries the Database on Its Own

The coolest part of the project is the Discord chatbot. She types a question in Portuguese (“how were my posts this week?”) and the bot calls the right tools, queries the database, and answers with real data.

The secret is RubyLLM’s tool calling. Every tool is a Ruby class with description and params:

class PostPerformanceTool < RubyLLM::Tool
  description "Returns post performance stats: baseline, " \
              "breakdown by content type, best times, best hashtags."

  param :username, type: :string, desc: "Profile username (e.g. milaoliveira.png)"
  param :analysis, type: :string,
    desc: "Type: baseline, content_types, timing, hashtags",
    required: false

  def execute(username:, analysis: "baseline")
    profile = SocialProfile.find_by(username: username.to_s.strip)
    return "Profile '#{username}' not found." unless profile

    case analysis.to_s.strip.downcase
    when "baseline"
      baseline = PostPerformance.compute_baseline(profile)
      {
        username: profile.username,
        post_count: baseline[:post_count],
        mean_views: baseline[:mean_views].round(0),
        stddev_views: baseline[:stddev_views].round(0),
        mean_engagement: baseline[:mean_engagement].round(2)
      }
    when "timing"
      PostPerformance.timing_breakdown(profile).first(10).map do |entry|
        { day: days[entry[:day]], hour: "%02d:00" % entry[:hour],
          avg_percentile: entry[:avg_percentile].round(1) }
      end
    # ...
    end
  end
end

The LLM gets the list of 40+ tools with their descriptions, decides which ones to call with which parameters, gets the results back, and formulates the answer. The Discord bot shows real-time status while it works: “Querying profile metrics… Checking growth… Analyzing post performance… (3 queries)”.

The trick was making each tool return structured data (Hashes and Arrays), not formatted text. The LLM is much better at formatting raw data into a conversational reply than at parsing semi-structured text.

Another detail that only showed up in real use: clamping parameters. When the LLM asks for limit: 999 on a parameter that maxes out at 50, instead of returning an error, I do [[val.to_i, 1].max, 50].min. The LLM gets parameters wrong more than you’d think. Every error generates a correction round-trip that costs tokens and time.

Composable Prompts: YAML > Hardcoded Strings

Every prompt in the system lives in YAML under config/prompts/. Each one has a system (fixed instructions), a template (with data interpolation), and optionally includes (reusable snippets):

module Llm
  class PromptBuilder
    PROMPTS_DIR = Rails.root.join("config", "prompts")

    class << self
      def build(name, data = {})
        prompt = load_prompt(name)
        base = load_prompt(:_base_context)

        includes = resolve_includes(prompt["includes"])
        system_parts = [base["system"], includes, prompt["system"]]
          .compact.reject(&:blank?)
        system_message = system_parts.join("\n\n")
        user_message = interpolate(prompt["template"], data)

        { system: system_message, user: user_message }
      end
    end
  end
end

The _base_context.yml carries info every prompt needs (who the influencer is, niches, audience, general guidelines). The snippets in config/prompts/snippets/ solve recurring problems:

• null_vs_zero.yml — the nil/zero distinction explained above
• never_invent.yml — “NEVER invent data, only analyze what’s actually present”
• json_only.yml — “respond ONLY in valid JSON”

When a prompt needs any combination of these, you just list them in includes. No duplication, no risk of conflicting instructions across prompts.

This decision came out of a real bug: two different prompts gave contradictory instructions on how to handle null values. One said “use 0”, the other said “use null”. The LLM obeyed one or the other depending on the day. Centralizing in snippets killed off an entire class of inconsistency.

Discovery Pipeline: Autonomous Profile Mining

The initial system started from a manual list of competitors and sponsors. But the influencer lives in a dynamic ecosystem — new creators show up every week, brands appear and disappear. The discovery pipeline automates that.

It runs every Friday at 2 a.m. It starts by mining data we already have in the database: who’s being @mentioned in posts, who comments often and with high engagement, which profiles show up in bio links, who uses brand hashtags (#publi, #parceria), which Linktree links point to other creators. All pure SQL, no API calls, no rate-limit risk.

The candidates that come out of that get validated against the platforms’ APIs (does the Instagram exist? Is the YouTube channel real?), then enriched with cross-platform connections (if we validate an Instagram, we look for the YouTube and X of the same creator).

A batch LLM call evaluates all the candidates, classifies each one as competitor, potential sponsor or irrelevant, and assigns relevance and niche-fit scores. The top 3 become actually tracked profiles — the system starts collecting data from them automatically.

After that, it groups everything into Creator entities. The influencer is depth 0. Direct competitors, depth 1. Mentions of competitors, depth 2. Maximum 3 degrees of separation, to avoid infinite cascade.

From Weekly Report to Daily Digests: Listening to the User

The original plan was a weekly email report with 9 sections. But midway through I decided it would be more dynamic to not even leave Discord and have that information always available.

I pivoted to 5 daily digests on Discord:

• Monday — Performance Recap (followers, growth, top posts)
• Tuesday — Competitor Radar (snapshot, news, strategies)
• Wednesday — Content Playbook (schedule, trends, hashtags)
• Thursday — Opportunities and Pricing (brands, pricing, packages)
• Friday — Next Week (events, priority actions)

Every digest has numbered items with feedback buttons. She marks what she found useful and what she didn’t. That feedback feeds future analyses — the system learns which kinds of insight she values.

This change, which wasn’t in any plan, is probably what improved her experience the most. Every morning at 9 a.m. she opens Discord and gets a fresh, digestible, actionable summary. The weekly email got demoted to backup, commented out in recurring.yml.

The Oracle: Context the Algorithm Doesn’t See

Social media data without external context is kind of useless. “This post got 3x more views than average” is a fact. “This post got 3x more views because it dropped on the day the new Sonic trailer came out” is an insight.

The Oracle is the subsystem that provides that context.

The most critical part is convention tracking: CCXP, Anime Friends, BGS, and dozens of other geek calendar events. Dates, prices, venues, ticket links, the event’s Instagram/X accounts. It monitors daily for changes (date moved, cancellation, guest announcement). The influencer plans her entire calendar around conventions. If CCXP changes its date, she needs to know that day, not the following week.

It also tracks movie/series releases via TMDB, games via IGDB (with Twitch OAuth), anime via AniList — all filtered for geek content, with a 90-day forward window. Franchise anniversaries (using TMDB, IGDB, AniList, Wikimedia) and Brazilian holidays with floating-date calculation. Yes, there’s an Easter calculator in the code based on the computus algorithm. And news via RSS and X/Twitter scraping every 6 hours, classified by relevance to the niche.

The event tracker scrapes convention sites with headless Chrome and uses the LLM at temperature 0.1 to extract structured metadata (date, price, venue). It has a regex fallback for Brazilian-format dates (“15 de março de 2026”). Deduplication by fuzzy name matching + date proximity — because “CCXP 2026”, “CCXP São Paulo 2026” and “CCXP SP” are the same event.

SQLite in Production: Yes, It Works

SQLite3 in production. With WAL mode, a single writer at a time is enough because the system has a predictable write pattern (sequential jobs, never concurrent in the same second). The data lives in a Docker bind mount (./data/storage:/rails/storage) and backup is cp data/storage/*.db backups/.

Rails 8 treats SQLite as a first-class citizen. Solid Queue and Solid Cache run on SQLite without issues. The overhead of a Postgres for a system that serves one person doesn’t justify itself.

25+ Scheduled Jobs

The config/recurring.yml has 25+ jobs with staggered schedules so the machine doesn’t get overloaded:

production:
  youtube_collection:
    class: Collection::YoutubeCollectorJob
    schedule: every day at 3am

  instagram_collection:
    class: Collection::InstagramCollectorJob
    schedule: every day at 4am

  x_collection:
    class: Collection::XCollectorJob
    schedule: every 2 days at 5am

  oracle_events:
    class: Oracle::EventTrackerJob
    schedule: every Monday at 2am

  convention_monitor:
    class: Oracle::ConventionMonitorJob
    schedule: every day at 5am

  discovery_pipeline:
    class: Discovery::OrchestratorJob
    schedule: every Friday at 2am

  comment_sentiment:
    class: Analysis::CommentSentimentJob
    schedule: every Sunday at 5am

  weekly_analysis:
    class: Analysis::WeeklyAnalysisJob
    schedule: every Sunday at 6am

Collection runs in the early morning (3am-5am). The Oracle intelligence kicks off Monday at 2am. Discovery on Friday at 2am. Heavy analysis (sentiment, strategy) on Sunday when there’s no digest to deliver. Digests Monday through Friday at 9am, each day on a different theme. Maintenance (cleaning up finished jobs, URL health checks, aggregating old data) fills the gaps.

The pattern is deliberate: no heavy job competes with the morning digests. If the weekly analysis runs late, Monday’s digest still goes out because it uses Saturday’s collection data, not Sunday’s analysis.

What You Can’t Predict Without Running It

Some things I only found out after the system was in production.

Instagram blocks scraping at random. It doesn’t matter how stealth your browser is. The initial setup was scraping via Ferrum only. Right off the bat I added Apify as the primary source (paid API, more reliable) and the scraping became fallback.

LLMs hallucinate timestamps. I asked the bot to create a reminder for “tomorrow at 3pm” and it calculated a date in 2024. The fix was to inject current_datetime into every prompt that touches time and instruct it explicitly: “calculate based on current_datetime, convert to ISO 8601 with UTC-3”.

Discord has a 2000-character per-message limit, which seems obvious until your bot sends a 4000-char analysis and Discord just truncates it. I built an automatic split that breaks at the last \n before the limit.

Tool calls fail on parameters more often than I expected. The LLM asks for limit: 100 when the max is 50, or sends the username without the @ when it should have. Silent clamping ([[val.to_i, 1].max, 50].min) and input normalization (.strip, .delete("@")) on every tool killed off an entire category of errors that were burning tokens in retry loops.

Conventions change dates more than I imagined. I added an announcement system that tracks every change (date, venue, price, cancellation) with a timestamp. The event tracker runs every Monday, but the convention monitor runs DAILY, because the last thing the influencer wants is to find out a convention moved its date after she already booked the hotel.

The Bot as an Interface

The smartest decision in the project was not building a web interface. Discord is already where the influencer spends her day. The bot lives there, available any time. She types “what should I post this week?” and gets a contextualized answer with data from her own posts, from competitors, from the events calendar, from hashtag trends, and from the season’s anime/games.

The chatbot combines several tools into one answer. If she asks about content strategy, the LLM calls: content digest + events calendar + hashtag trends + seasonal anime + Steam games. Five database queries, all stitched into a conversational reply in Portuguese.

There’s even a “deep thinking” mode that activates when it detects words like “research”, “analyze”, “investigate”. In that mode, the bot uses ALL relevant tools, runs multiple queries, cross-references data across sources.

Conclusion

The whole project shipped in 3 days, from zero to production, collecting real data, sending out digests every morning. No Jira, no sprint planning, no 6-month discovery phase. An IDEA.md with the user’s wishes in her own words, iterative development commit by commit, and continuous validation with the person who’s going to actually use it.

If I had started from the architecture, I’d have spent weeks designing a dashboard she would never open. Starting from the wish, the system ended up being a Discord chatbot she uses every day. Async jobs that aren’t idempotent are time bombs — the rate limit is going to blow, the scraping is going to fail, the container is going to restart, and if the job can’t survive that without duplicating data, the system doesn’t work.

In the end, the measure of success for the project isn’t lines of code, isn’t the number of passing tests, isn’t elegant architecture. It’s the influencer opening Discord on a Monday morning and having what she needs to plan the week.

And don’t forget to subscribe to my new newsletter The M.Akita Chronicles!

–

Every Rails project starts the same way: you build an admin panel. Active Admin, Administrate, or some homegrown CRUD. Tables, forms, buttons. And every week, you end up using 5% of the screens you built.

Now picture your admin panel as a conversation. You paste a link; the system processes it. You type /week and see the summary. /approve and the newsletter is scheduled. /ask akita how does the podcast pipeline work? and an AI explains the architecture of your own system to you.

That’s Discord as an operational interface. It’s not a hack — it’s the best CRUD interface there is for a team of one.

Why Discord Instead of a Web Admin?

Let’s be honest about what an admin panel demands:

1. Authentication: login, session, CSRF, password reset
2. Authorization: roles, permissions, who can do what
3. UI: tables, pagination, forms, client-side validation
4. Deployment: another route, another controller, another set of tests
5. Mobile: responsive? App? PWA?

And what Discord already gives you for free:

1. Auth: Discord handles it. You just check the author_id
2. Authorization: a list of admin IDs and you’re done
3. UI: embeds with colors, fields, thumbnails, reactions as status
4. Deployment: zero. Uses what’s already deployed
5. Mobile: native iOS and Android app, push notifications

The trade-off? It doesn’t fit everything. A complex CRUD with 20-field forms? Better off with a web admin. But for command/response operations — which are 90% of what you do day to day — Discord is unbeatable.

discordrb: A Gem That Works

The discordrb gem (shardlab fork, version 3.7.2) is the most mature one for Ruby. It’s not perfect — it has its quirks. But it genuinely works in production.

The minimal setup:

bot = Discordrb::Bot.new(
  token: token,
  intents: Discordrb::INTENTS[:server_messages] |
           Discordrb::INTENTS[:direct_messages] |
           (1 << 15)  # message_content intent
)

bot.message do |event|
  # Every message flows through here
end

bot.run

That (1 << 15) is the Message Content Intent. Without it, your bot receives events but event.content comes in empty. You need to enable it in the Discord Developer Portal > Bot > Privileged Gateway Intents. That’s the first trap that catches everyone.

I won’t walk through how to set up a Discord bot, there are plenty of tutorials for that already, easy to find online. I’ll focus only on my use case as an example.

Pattern 1: Parser + Dispatcher

Mixing command parsing with business logic is a recipe for spaghetti. Split it into three layers:

Discord Event → Parser → Dispatcher → Job/Service

The runner (the thing that talks to the Discord API) is deliberately dumb:

bot.message do |event|
  next if event.author.bot_account?

  parsed = SlashCommandParser.parse(event.content, attachments: urls)

  case parsed
  when SlashCommandParser::Command
    CommandDispatcher.dispatch(parsed, channel_id: channel_id)
    event.message.react("\u{2705}")  # checkmark
  when SlashCommandParser::Submission
    ProcessMessageJob.perform_later(url: parsed.url, tags: parsed.tags)
    event.message.react("\u{1F916}")  # robot
  end
rescue StandardError => e
  event.message.react("\u{274C}")  # red X
end

Three instant visual results: checkmark (command accepted), robot (URL being processed), red X (error). The user knows what happened without waiting for any text response.

The parser returns typed objects, not strings. The dispatcher runs a giant case but each handler is an isolated method. Each handler calls a job or service. No business logic in the runner.

Evolution: Discord Application Commands

The initial version parsed raw text — the user typed /week and the parser interpreted it. It works, but it has limits: no autocomplete, no argument validation, no inline documentation.

Discord has a native Application Commands system — slash commands registered with the API that show up with autocomplete, description, and typed parameters. When the user types /, Discord displays every available command with its description.

bot.register_application_command(:week, "List this week's stories", server_id: guild_id)
bot.register_application_command(:approve, "Approve newsletter for sending", server_id: guild_id)
bot.register_application_command(:ask, "Ask AI a question", server_id: guild_id) do |cmd|
  cmd.string("question", "Your question", required: true)
  cmd.string("personality", "AI personality", choices: { "Akita" => "akita", "Marvin" => "marvin" })
end

The handler uses bot.application_command instead of parsing text:

bot.application_command(:week) do |event|
  CommandDispatcher.dispatch_week(channel_id: event.channel.id)
  event.respond(content: "Listing stories...")
end

Both systems coexist: Application Commands for those who prefer autocomplete, raw text for those who prefer typing fast. The dispatcher is the same — the only difference is how the command arrives.

Pattern 2: Reactions as Status

The most underrated feature of Discord for bots is reactions. They’re instant visual feedback that doesn’t pollute the channel with messages:

• Checkmark = command received and queued
• Robot = async processing started
• Red X = error (details in the embed that follows)

The user pastes a link. Sees the robot appear. 30 seconds later, a rich embed shows up with title, summary, image and AI commentary. If something fails, a red embed appears with the error message.

That beats any loading spinner in a web UI.

Pattern 3: Rich Embeds as Dashboard

Discord embeds are surprisingly powerful:

embed = {
  title: "Story Preview",
  url: source_url,
  color: 0xFF4500,           # orange-red for high priority
  description: summary,
  thumbnail: { url: image },  # article image
  fields: [
    { name: "M.Akita diz", value: akita_comment, inline: false },
    { name: "M.Arvin diz", value: marvin_comment, inline: false },
    { name: "File", value: "`stories/2026-02-16-titulo.md`", inline: false }
  ],
  footer: { text: "fire high | tech_news | verified" }
}

Discordrb::API::Channel.create_message(token, channel_id, "", false, [embed])

Colors signal priority (red = high, amber = medium, green = low). The footer shows score, section and fact-check status all on a single line. You glance at it and know the state of things.

For reports, multiple embeds side by side (Discord accepts up to 10 per message) work as a mini-dashboard. The /week command lists every story with inline actions — /load @a3f2b1 to see details, /delete @a3f2b1 to remove it. The hash is stable (based on the file path), so it doesn’t shift when you delete another story.

Pattern 4: Context Per Channel

When the user types /load #3, the #3 refers to the most recent listing. But what if two channels are being used at the same time?

class ChannelContext < ApplicationRecord
  EXPIRY_DURATION = 2.hours

  def self.for_channel(channel_id)
    find_or_create_by!(channel_id: channel_id.to_s)
  end

  def set_week_stories!(hash)
    update!(week_stories_json: hash.to_json, expires_at: EXPIRY_DURATION.from_now)
  end

  def resolve_story_reference(ref)
    if ref.match?(/\A@[a-f0-9]+\z/i)
      # Hash reference (stable across re-listings)
      hash = ref.delete("@").downcase
      week_stories.values.find { |path| md5_prefix(path) == hash }
    elsif ref.match?(/\A#?\d+\z/)
      week_stories[ref.delete("#")]
    end
  end
end

Each channel has its own context with a 2-hour expiration. /week stores the number→file mapping. Then /load #3 queries that context. If it expired, the bot says “run /week first”.

And the most useful detail: hash-based references (@a3f2b1) instead of numbers. When you delete story #2, #3 becomes #2 — but the hash @a3f2b1 still points to the same file. That avoids the classic “I deleted the wrong one because the list shifted”.

Pattern 5: Simple Admin Check

No complex RBAC. A list of IDs:

ADMIN_COMMANDS = %i[delete update_score approve newsletter publish_blog].freeze

def self.dispatch(command, channel_id:, author_id:)
  if ADMIN_COMMANDS.include?(command.type) && !admin?(author_id)
    send_error(channel_id, "Permission denied. Admin privileges required.")
    return
  end
  # ...
end

def self.admin?(author_id)
  admin_ids = ENV["DISCORD_ADMIN_USER_IDS"].to_s.split(",")
  return true if admin_ids.empty?  # dev: no IDs = everything allowed
  admin_ids.include?(author_id)
end

In dev, without DISCORD_ADMIN_USER_IDS set, everything is allowed. In production, it’s a list of Discord user IDs. No database, no roles table, no middleware. Ten lines handle authorization.

Pattern 6: Async Operations with Feedback

Slow operations (generating an image, processing an article, calling an AI) go to background jobs. Visual feedback comes in three beats:

def self.handle_ask(personality, question, attachments, channel_id)
  # 1. Immediate feedback: "I'm thinking"
  thinking_id = DiscordNotifier.send_message(channel_id, content: "Thinking...")

  # 2. Job does the heavy lifting in the background
  AskJob.perform_later(
    question,
    channel_id: channel_id,
    thinking_message_id: thinking_id
  )
end

# In AskJob:
def perform(question, channel_id:, thinking_message_id: nil)
  result = AiChat.ask_multimodal(question, tools: [GenerateImageTool])

  # 3. Remove "Thinking..." and show result
  DiscordNotifier.delete_message(channel_id, thinking_message_id)
  DiscordNotifier.send_message(channel_id, content: "**Marvin:** #{result[:text]}")
end

The “Thinking…” shows up instantly, the job runs in the background, and when it finishes the temporary message disappears and the real result appears. If the job fails, “Thinking…” disappears and an error embed shows up.

Without this, the user sends a question and stares at the screen not knowing if the bot heard them. Terrible UX.

Pattern 7: RubyLLM + Tool Calling on Discord

The most powerful part: giving the LLM tools. /ask has three tools available: GenerateImageTool (generates images via Gemini), WebSearchTool (searches the web via Brave Search), and WebFetchTool (fetches and summarizes web pages). The LLM decides on its own which one to use based on the question. When the user asks “generate an image of a cat programming”, the LLM picks the right tool:

class GenerateImageTool < RubyLLM::Tool
  description "Generate an image using Gemini. Use when the user asks to create or draw."
  param :prompt, desc: "Image description"
  param :aspect_ratio, desc: "1:1 or 16:9", required: false

  def execute(prompt:, aspect_ratio: "1:1")
    image_data = ImageGenerator.generate(prompt: prompt)
    return "Failed to generate image" unless image_data

    path = save_temp_file(image_data)
    Thread.current[:generated_images] << path

    "Image generated successfully. Tell the user it's ready."
  end
end

The Thread.current[:generated_images] is the trick to pass data back from the tool to the job. The LLM calls the tool during chat.ask, the tool saves the file and registers the path. After chat.ask returns, the job grabs the paths and sends them to Discord as file uploads.

Why thread-local and not a direct return? Because the LLM can call multiple tools within a single response, and the tool’s return value goes back to the LLM (not to your code) — the LLM decides what to say to the user. Thread-local is the side channel for your code to know what happened.

Pattern 8: Production Status Notifications

Every content generation job notifies a dedicated channel:

module DiscordStatus
  def notify_start(label)
    DiscordNotifier.send_to_status_channel("Starting #{label}...")
  end

  def notify_done(label)
    DiscordNotifier.send_to_status_channel("#{label} complete.")
  end

  def notify_error(label, error)
    DiscordNotifier.send_to_status_channel("#{label} FAILED: #{error}")
  end
end

The status channel is separate from the operations channel. When the 8 content generation jobs run on Sunday at 5pm, the status channel turns into a real-time log:

Starting Anime Ranking...
Starting Hacker News...
Starting YouTube Digest...
Anime Ranking complete.
YouTube Digest complete.
Hacker News complete.
Starting Market Recap...  (wave 2, after world events)
...

In the morning, if something went wrong, you open Discord on your phone and you know exactly what — no SSH into the server, no grep in logs.

And when the bot restarts after a deploy:

bot.ready do |_event|
  status_channel = ENV["DISCORD_STATUS_CHANNEL_ID"]
  DiscordNotifier.send_message(status_channel, content: "Bot reconnected and ready.")
end

Simple, but you know the deploy worked without checking anything.

Pattern 9: Cross-App Communication

The system has two Rails apps that need to talk to each other. The newsletter needs to notify Discord when it finishes assembling an edition. But the newsletter has no Discord connection — marvin-bot is the one that does.

Solution: HTTP relay.

# In the newsletter — send it to marvin-bot
class DiscordRelayClient
  def self.send_embed(title:, description:, color:)
    post("/api/discord_notify",
      type: "embed",
      payload: { title: title, description: description, color: color }
    )
  end
end

# In marvin-bot — receive it and forward to Discord
class Api::DiscordNotifyController < ApplicationController
  def create
    case params[:type]
    when "embed"
      DiscordNotifier.send_embed(status_channel, params[:payload])
    when "message"
      DiscordNotifier.send_message(status_channel, content: params[:payload][:content])
    end
  end
end

The newsletter speaks HTTP. marvin-bot translates it to Discord. A shared ADMIN_TOKEN authenticates. Every method rescues errors and returns nil — if Discord is down, the newsletter doesn’t lock up. Fire and forget.

But there’s a second, more interesting cross-app flow: the podcast trigger. When the newsletter is approved, it needs to tell marvin-bot to generate the podcast:

# In the newsletter — trigger podcast generation on marvin-bot
class MarvinBotClient
  def self.trigger_podcast(date:)
    post("/api/trigger/podcast", date: date.to_s)
  end
end

That kicks off an entire pipeline on marvin-bot: two-pass LLM script → per-turn TTS on the GPU → assembly with loudnorm → S3 upload. And the newsletter’s PublishAndSendJob waits (via retry_on PodcastNotReady) until the podcast is ready. Two apps, two backend languages (Ruby and Python), connected by fire-and-forget HTTP with result polling. It’s not elegant — but it works every single week with no intervention.

Pattern 10: Integrated Cost Tracking

Every AI call is tracked with tokens and estimated cost:

def self.create_chat(caller:, model:, provider:)
  chat = RubyLLM.chat(model: model, provider: provider)
  chat.on_end_message do |message|
    ApiUsage.create!(
      caller_name: caller,
      input_tokens: message.input_tokens,
      output_tokens: message.output_tokens,
      cost_usd: estimate_cost(model, message)
    )
  end
  chat
end

And on Discord: /cost shows spending by month, year, and by provider. No separate dashboard, no Grafana, nothing. One command and the information that matters.

Pattern 11: Never Fail Silently

This is the pattern I should have implemented from the start, but I only learned it the hard way — in production.

The project has ~10 daily jobs that fetch data from external sources (Hacker News, GitHub Trending, Morningstar, etc.) and post embeds to Discord. Each client follows a “defensive” pattern:

# The pattern that LOOKS right:
class DailyDevClient
  def self.fetch_popular(limit: 10)
    response = HTTParty.get(API_URL, headers: { "Authorization" => "Bearer #{token}" })
    return [] unless response.success?
    parse(response.body)
  rescue StandardError => e
    Rails.logger.warn("DailyDevClient failed: #{e.message}")
    []
  end
end

# And in the job:
class DailyDailyDevJob < ApplicationJob
  def perform
    posts = DailyDevClient.fetch_popular(limit: 10)
    return if posts.empty?  # ← THE PROBLEM
    # ... posts embed to Discord
  end
end

This code never crashes. Never raises an exception. Never fills the log with errors. It’s the most “robust” code possible.

It’s also completely useless for diagnosis. When I deployed and ran the daily jobs manually, only one of ten worked. But there was no error in the logs. None. return [] unless response.success? swallowed the HTTP 401 without logging. return if posts.empty? discarded the result without telling anyone. All green, all silent, zero data.

The fix has two parts:

Part 1: Clients log the HTTP code:

unless response.success?
  Rails.logger.warn("DailyDevClient: API returned HTTP #{response.code}")
  return []
end

It sounds obvious, but it’s easy to forget when you write return [] as a defensive reflex. response.code is the information that distinguishes “expired token” (401) from “rate limited” (429) from “API down” (503). Without it, everything looks the same: empty array.

Part 2: Jobs warn on Discord when they have no data:

module DailyDiscordEmbed
  def report_empty(title)
    Rails.logger.warn("#{self.class.name}: #{title} returned no results")
    channel_id = Rails.application.config.discord.channel_ids.first
    return unless channel_id.present?

    embed = {
      title: "⚠️ #{title}",
      description: "#{self.class.name} returned no results. Check logs.",
      color: 0xFFA500,  # orange = warning, not red = error
      timestamp: Time.current.iso8601
    }
    DiscordNotifier.send_embed(channel_id, embed)
  rescue StandardError => e
    Rails.logger.error("#{self.class.name} empty report failed: #{e.message}")
  end
end

Now when a daily job brings back no data:

def perform
  posts = DailyDevClient.fetch_popular(limit: 10)
  if posts.empty?
    report_empty("daily.dev Popular")
    return
  end
  # ...
end

An orange embed appears on Discord. In the morning, I open the channel and see: “⚠️ daily.dev Popular returned no results”. I check the logs and find: “DailyDevClient: API returned HTTP 401”. Expired token. Fixed in 2 minutes.

Without this pattern, I would have discovered it weeks later — when someone asked “why are there never any daily.dev posts?”.

The lesson: rescue => [] is not error handling. It’s error hiding. Every failure point needs two signals: a log with the technical detail (HTTP code, exception message) and a visual notification in the channel where you’re already looking (Discord). If the bot IS your operational interface, bot failures need to show up ON the interface.

Pattern 12: Conversations With Memory (Multi-Turn /ask)

The first version of /ask created a brand new RubyLLM::Chat on every invocation. It worked, but it was like talking to someone with amnesia:

/ask what is Ruby?
→ Ruby is a programming language created by Matz in 1995...

/ask compare it with Python
→ Compare what with Python? Could you be more specific?

ruby_llm already keeps history internally — every chat.ask() appends to the message list and sends the full context to the model. What was missing was persisting the Chat object between invocations.

The solution is an in-memory store with three safeguards:

class AskSessionStore
  MAX_SESSIONS = 100       # total across all users
  SESSION_TTL = 2.hours    # inactivity timeout
  MAX_MESSAGES = 50        # ~25 exchanges, then auto-reset

  Session = Struct.new(:chat, :last_used, keyword_init: true)

  def get_or_create(author_id, personality, system_prompt:, tools:)
    synchronize do
      cleanup_expired
      key = [author_id, personality]

      if (session = @sessions[key])
        session.last_used = Time.current
        if session.chat.messages.length > MAX_MESSAGES
          @sessions.delete(key)
          return create_session(key, system_prompt: system_prompt, tools: tools)
        end
        session.chat
      else
        evict_oldest if @sessions.size >= MAX_SESSIONS
        create_session(key, system_prompt: system_prompt, tools: tools)
      end
    end
  end
end

The key is (author_id, personality) — each user has separate sessions for Marvin and for Akita. Volatile on purpose: restart the server, lose the history. No database, no serialization, no complexity. It’s working memory, not persistence.

/ask clear resets the session. Without it, there’s no way to “start over” when the conversation gets tangled.

Now:

/ask what is Ruby?
→ Ruby is a programming language created by Matz in 1995...

/ask compare it with Python
→ Ruby and Python have similar philosophies — both prioritize programmer
  happiness — but Ruby embraces blocks and metaprogramming while Python
  prefers explicitness...

The LLM knows “compare” refers to Ruby because the session history includes the previous question. That’s the difference between a chatbot and an assistant.

Pattern 13: Registering Application Commands (Native Autocomplete)

The Application Commands section above showed the simplified concept. In practice, registering 18 commands with subcommands, typed parameters and choices demands a dedicated structure. Here’s how the project handles it.

The Problem With Raw Text

When the bot only parses text, the user has to memorize the syntax:

/update score #1 #2 #3 high       ← works
/update score #1 #2 #3 alta       ← fails silently
/update scoree #1 high             ← ignored

No autocomplete, no parameter validation, no inline documentation. The user types / and has no idea what’s available.

The DiscordCommands Module

All command definitions live in a separate module with two public methods: register! (registers the commands with the Discord API) and setup_handlers! (wires the handlers to the bot):

module DiscordCommands
  SCORE_CHOICES  = { "High" => "high", "Medium" => "medium", "Low" => "low" }.freeze
  SECTION_CHOICES = {
    "Tech" => "tech", "Global" => "global", "Financial" => "financial",
    "Q&A" => "qa", "Entertainment" => "entertainment", "Open Source" => "opensource",
    "Product" => "product", "Book" => "book"
  }.freeze
  PERSONALITY_CHOICES = { "Marvin (default)" => "marvin", "Akita" => "akita" }.freeze

  def self.register!(bot)
    server_id = Rails.application.config.discord.server_id
    sid = server_id.present? ? server_id.to_i : nil

    register_week(bot, sid)
    register_add(bot, sid)
    register_update(bot, sid)
    register_ask(bot, sid)
    # ... 14 more commands
  end

  def self.setup_handlers!(bot)
    setup_week_handlers(bot)
    setup_add_handler(bot)
    setup_update_handlers(bot)
    setup_ask_handlers(bot)
    # ... 14 more handlers
  end
end

Guild vs Global

The server_id (or sid) controls the registration scope. With server_id, the command shows up instantly on the specified server. Without it, the command is global — available on every server, but can take up to an hour to propagate.

For a private bot doing internal operations, always go guild-scoped. The DISCORD_SERVER_ID env var is set at deploy time:

sid = server_id.present? ? server_id.to_i : nil
bot.register_application_command(:week, "Story list and weekly report", server_id: sid)

If sid is nil, discordrb registers globally. In dev it’s convenient; in production, guild-scoped is faster and lets you have different commands per server.

Anatomy of a Command

The simplest method — no parameters:

def self.register_count(bot, sid)
  bot.register_application_command(:count, "Show story count for this week", server_id: sid)
end

With typed parameters:

def self.register_add(bot, sid)
  bot.register_application_command(:add, "Submit a URL for the newsletter", server_id: sid) do |cmd|
    cmd.string(:url, "The URL to submit", required: true)
    cmd.string(:tags, "Tags (e.g. #tech #high)")
    cmd.string(:comment, "Optional comment about this link")
  end
end

Discord renders this as an inline form: required url field, optional tags and comment. The user sees each parameter’s description as they fill it in.

Subcommands: Grouping Actions

Complex commands use subcommands. /update on its own does nothing — the user has to pick what to update:

def self.register_update(bot, sid)
  bot.register_application_command(:update, "Update story properties", server_id: sid) do |cmd|
    cmd.subcommand(:score, "Update story priority score") do |sub|
      sub.string(:stories, "Story numbers (e.g. #1 #2 #3 or 1,2,3)", required: true)
      sub.string(:level, "Priority level", required: true, choices: SCORE_CHOICES)
    end
    cmd.subcommand(:tag, "Update story section tag") do |sub|
      sub.string(:stories, "Story numbers (e.g. #1 #2 #3 or 1,2,3)", required: true)
      sub.string(:section, "Section tag", required: true, choices: SECTION_CHOICES)
    end
    cmd.subcommand(:image, "Update story image") do |sub|
      sub.string(:stories, "Story numbers (e.g. #1 #2 #3 or 1,2,3)", required: true)
      sub.attachment(:file, "Image file (omit for AI generation)")
    end
    # ... more subcommands: title, description, comment, source
  end
end

When the user types /update, Discord shows a list of subcommands: score, tag, title, description, comment, image, source. Pick score and the stories field (free text) and level field (dropdown with High/Medium/Low) appear. Syntax errors become impossible.

Choices: Native Dropdowns

The SCORE_CHOICES hash becomes a dropdown on Discord. The key is the visible label (“High”), the value is what arrives in the handler (“high”):

SCORE_CHOICES = { "High" => "high", "Medium" => "medium", "Low" => "low" }.freeze

# In the registration:
sub.string(:level, "Priority level", required: true, choices: SCORE_CHOICES)

The user doesn’t have to remember whether it’s “high”, “HIGH”, “alta”, or “3”. Pick it from the dropdown and done. That eliminates an entire category of input errors.

Attachments: File Uploads

Discord supports attachment-type parameters — the user can drag a file straight into the command:

cmd.subcommand(:image, "Update story image") do |sub|
  sub.string(:stories, "Story numbers (e.g. #1 #2 #3 or 1,2,3)", required: true)
  sub.attachment(:file, "Image file (omit for AI generation)")
end

In the handler, the resolved attachments come through as Discord CDN URLs:

def self.resolve_attachments(event)
  return [] unless event.resolved&.attachments&.any?
  event.resolved.attachments.values.map(&:url)
end

Lifecycle: Where to Register, Where to Wire Handlers

This is the point that confuses people most. The handlers have to be registered before bot.run. The registration with the Discord API can happen inside bot.ready (which fires after the WebSocket connection):

class MarvinBotRunner
  def self.run!
    bot = Discordrb::Bot.new(token: token, intents: ...)

    # 1. Handlers BEFORE bot.run (otherwise the bot doesn't know how to respond)
    DiscordCommands.setup_handlers!(bot)

    bot.ready do |_event|
      # 2. API registration AFTER connection (idempotent, safe on reconnect)
      DiscordCommands.register!(bot)
    end

    bot.run
  end
end

Why inside bot.ready? Because the bot can reconnect (Discord closes WebSockets periodically). register! is idempotent — registering the same command twice doesn’t duplicate it, it just updates. Putting it in ready makes sure the commands exist even after a reconnect.

Bridge: Application Command → CommandDispatcher

The most elegant part of the architecture: the Application Command handler has no business logic. It translates Discord’s parameters into the format the CommandDispatcher already expects:

def self.dispatch_interaction(event, type, match: [nil], attachments: [])
  event.respond(content: "\u{2705}", ephemeral: true)  # checkmark visible only to the author
  command = SlashCommandParser::Command.new(
    type: type,
    args: { match: match, attachments: attachments }
  )
  CommandDispatcher.dispatch(command,
    channel_id: event.channel.id.to_s,
    message_id: nil,
    author_id: event.user.id.to_s
  )
rescue StandardError => e
  Rails.logger.error("Discord interaction error (#{type}): #{e.message}")
end

Each subcommand handler is a one-liner that assembles the args and calls dispatch_interaction:

bot.application_command(:update).subcommand(:score) do |event|
  stories = event.options["stories"]
  level = event.options["level"]
  dispatch_interaction(event, :update_score, match: [nil, stories, nil, level])
end

CommandDispatcher doesn’t know if the command came from raw text or from an Application Command. Same logic, same authorization, same jobs. No duplicated code.

The Result

The project registers 18 Application Commands with combinations of subcommands, typed parameters, dropdowns and file uploads. The user types / and sees everything available with descriptions. Pick a command and Discord guides you field by field. Syntax errors are impossible — Discord validates before sending.

And both systems coexist: people who prefer autocomplete use Application Commands, people who prefer to type fast use raw text. CommandDispatcher receives both the same way. Adding a new command means adding a register_*, a setup_*_handler, and a dispatcher method — without touching the runner.

The discordrb Pitfalls

It’s not all roses. Some real pain points:

Gateway disconnects: The WebSocket to Discord drops every once in a while. discordrb reconnects automatically, but your bot.ready and bot.message handlers need to be resilient to reconnects.

Message Content Intent: Since 2022, bots in more than 75 servers need approval to read message content. For private bots (which is the case for internal operations), that’s a non-issue. But if you plan to distribute the bot, get ready for paperwork.

API Rate Limits: Discord rate-limits per route. Sending 10 embeds at once to the same channel? You’ll hit the limit. discordrb handles rate limits internally, but calls that are too fast cause visible delays.

Embed Limits: Title max 256 chars. Description 4096. Field value 1024. Exceeded them? Silent error. Always truncate before sending.

File Uploads: 25MB limit on the free plan, 50MB with Nitro. For AI-generated images that’s never an issue, but if you’re shipping PDFs or audio, be careful.

When NOT to Use Discord as Admin

• Complex forms: editing 15 fields on a record? Web screen
• Bulk operations: importing a CSV with 1000 records? Script
• Data visualization: charts, analytical dashboards? Grafana/Metabase
• Multi-step approval: workflows with 5 approval stages? You need persisted state

But for day-to-day operations — curating content, approving newsletters, monitoring jobs, checking costs, talking to AI — Discord is the most productive interface I’ve ever used. And the best part: the subscribers will never know their weekly newsletter was curated by a guy typing commands into Discord on his phone while drinking coffee.

Conclusion

Using Discord as an admin panel isn’t laziness — it’s pragmatism. The best interface is the one you already use all day long. Auth, push notifications, mobile, rich formatting, file sharing — all free. You only build the business logic.

The ruby_llm gem with tool calling takes the bot from “command executor” to “assistant that thinks”. Add session memory and it thinks and remembers. When the LLM can generate images, search the web, keep context across questions, and answer questions about the architecture of its own system — that’s when it stops being CRUD and becomes a co-pilot.

And the Parser → Dispatcher → Job pattern keeps everything testable. The parser knows nothing about Discord. The dispatcher knows nothing about AI. The jobs know nothing about the interface. Swap any one of those layers and the others don’t even notice.

In the end, the best admin UI is the one that doesn’t need a separate deploy. And the worst bug is the one that fails in silence — if the bot is your operational interface, the bot’s failures need to show up on the interface, not hidden away in a log nobody reads.

And make sure to subscribe to my new newsletter The M.Akita Chronicles!

–

Sending emails looks trivial. Call an API, pass the HTML, send it. Done. Until the day you discover you sent the same newsletter twice to 300 people. Or that 50 emails bounced back and Amazon suspended your account. Or that your server restarted in the middle of a send and now you have no idea who got it and who didn’t.

Amazon SES is efficient — and brutally unforgiving with anyone who doesn’t treat every send as an operation that can fail in five different ways. In this post I’ll show the patterns that turn “sending email” into “sending email reliably”.

Why SES and Not Sendgrid/Mailgun/Resend?

Price. Period. SES charges $0.10 per thousand emails. Sendgrid charges $20/month for 50 thousand. For a small newsletter, both are cheap. But SES scales without changing plans — and since I’m already on AWS for S3, I don’t need yet another vendor.

The downside? SES is low-level. There’s no pretty drag-and-drop interface, no integrated analytics, no dedicated IP on the free plan. You get an API that accepts HTML and returns a message_id. The rest is your problem.

And that’s exactly where the danger lives.

The Fundamental Problem: At-Most-Once vs At-Least-Once

When an external service accepts your request, but your process dies before recording the success, you have a dilemma:

1. Resend: the subscriber may receive it twice (at-least-once)
2. Don’t resend: the subscriber may not receive it at all (at-most-once)

For financial transactions, at-least-once with deduplication is the standard. For email, at-most-once is preferable. Nobody complains about not receiving a newsletter. Everybody complains about receiving two.

This defines the whole architecture: when in doubt, don’t resend.

Pattern 1: One Record Per Recipient

The most common mistake in newsletter systems is iterating over a list of subscribers in a loop:

# ERRADO — se o job morrer no email 247, re-execução reenvia 1-246
subscribers.each do |sub|
  SesMailer.send(to: sub.email, body: html)
end

The solution is to create a delivery record before sending:

# Cria registros em batch
rows = subscriber_ids.map do |id|
  { newsletter_id: newsletter.id, subscriber_id: id, status: "pending" }
end
EmailDelivery.insert_all(rows, unique_by: [:newsletter_id, :subscriber_id])

# Enfileira um job individual por registro
EmailDelivery.where(newsletter: newsletter, status: ["pending", "failed"])
             .find_each do |delivery|
  SendSingleEmailJob.perform_later(delivery.id)
end

Each EmailDelivery is a state machine: pending → sending → sent. If the job dies, the record stays in sending — and is never automatically resent.

The unique_by guarantees idempotency: running this code twice doesn’t create duplicate records.

Pattern 2: Atomic Claiming

Two workers can’t send the same email. The claim needs to be atomic:

def claim_for_sending!
  updated = self.class
    .where(id: id, status: %w[pending failed])
    .update_all(
      status: "sending",
      sending_started_at: Time.current,
      send_attempts: Arel.sql("COALESCE(send_attempts, 0) + 1")
    )
  updated == 1  # true se ninguém pegou antes
end

This is an UPDATE with a WHERE — if two workers try at the same time, only one gets the updated == 1. The other gets 0 and gives up. No explicit locks, no race conditions.

The send_attempts is incremented atomically in the database, not in Ruby. That guarantees the correct count, even under concurrency.

Pattern 3: The SendSingleEmailJob Flow

Here’s the heart of the system. The individual send job follows a deliberate sequence:

class SendSingleEmailJob < ApplicationJob
  queue_as :mailer

  retry_on Aws::SESV2::Errors::TooManyRequestsException,
           wait: :polynomially_longer, attempts: 8

  def perform(delivery_id)
    ses_accepted = false
    delivery = EmailDelivery.find(delivery_id)

    # 1. Validação: assinante ainda ativo?
    unless subscriber_active?(delivery.subscriber)
      delivery.mark_failed!("Subscriber inactive")
      return
    end

    # 2. Guardrail: nunca reenviar o que já foi
    return if %w[sent unknown bounced].include?(delivery.status)

    # 3. Claim atômico
    return unless delivery.claim_for_sending!

    # 4. Renderiza e envia
    html = render_newsletter(delivery)
    message_id = ses_client.send_email(to: email, body: html)
    ses_accepted = true

    # 5. Marca sucesso
    delivery.mark_sent!(message_id)
  rescue Aws::SESV2::Errors::TooManyRequestsException => e
    # SES rejeitou ANTES de aceitar — seguro retentar
    delivery&.mark_failed!("Rate limited: #{e.message}")
    raise  # ActiveJob retry_on cuida do reagendamento
  rescue StandardError => e
    if ses_accepted
      # SES ACEITOU mas algo quebrou depois — estado ambíguo
      delivery&.mark_unknown!("Uncertain: #{e.message}")
    else
      delivery&.mark_failed!(e.message)
    end
  end
end

Pay attention to the ses_accepted variable. It’s the pivot of all the error logic:

• SES rejected (ses_accepted = false): safe to retry. The email wasn’t accepted; you can try again.
• SES accepted (ses_accepted = true): ambiguous state. The email was probably sent. Mark as unknown and never retry automatically.

This distinction is what prevents duplication. Most systems treat everything as “failed” and retry — which can result in duplicated emails when SES accepted but your process crashed before recording it.

Pattern 4: The Immutable Status Guardrail

Look at this line:

return if %w[sent unknown bounced].include?(delivery.status)

This isn’t defensive for no reason. It’s a business rule: those three states are terminal. Once a delivery reaches sent, unknown or bounced, no code in the system can automatically move it back to pending.

The only way to resend an unknown email is through manual intervention in the console. And that’s how it should be — if you’re not sure the email was delivered, the decision to resend belongs to a human, not to the system.

Pattern 5: Recovering Stuck Deliveries

If the worker crashes with a delivery in sending, it stays stuck in that state forever. A periodic job cleans this up:

class RecoverStaleDeliveriesJob < ApplicationJob
  STALE_AFTER = 30.minutes

  def perform
    stale = EmailDelivery.where(status: "sending")
                         .where("sending_started_at < ?", STALE_AFTER.ago)

    count = stale.update_all(status: "unknown", sending_started_at: nil)
    notify_team("#{count} stale deliveries moved to unknown") if count > 0
  end
end

Why unknown and not failed? Because a delivery that’s been in sending for 30 minutes may have been accepted by SES but not recorded. Moving it to failed would mean retrying — and potentially duplicating. unknown is the safe limbo: “I don’t know what happened; a human needs to decide”.

Pattern 6: Smart Retry on SES

SES has three categories of errors:

# Transitório — SES está ocupado, tente depois
retry_on Aws::SESV2::Errors::TooManyRequestsException,
         wait: :polynomially_longer, attempts: 8
retry_on Aws::SESV2::Errors::LimitExceededException,
         wait: :polynomially_longer, attempts: 5

# Permanente — sua conta ou email tem problema
rescue Aws::SESV2::Errors::MessageRejected => e
  delivery.mark_failed!(e.message)
  # NÃO re-tenta. O SES rejeitou esse email especificamente.

rescue Aws::SESV2::Errors::AccountSuspendedException => e
  delivery.mark_failed!(e.message)
  # Sua conta foi suspensa. Não adianta retentar nada.

The polynomially_longer is key: 3s, 18s, 83s, 293s… Polynomial backoff is more aggressive than exponential, which is good for SES — it wants you to slow down fast.

Never use retry_on StandardError. That retries programming errors (nil pointer, nonexistent method) that will fail forever.

Pattern 7: SES Tags for Traceability

Every email sent carries tags that let you correlate events later:

mailer.send_email(
  to: subscriber.email,
  subject: title,
  html_body: html,
  tags: {
    "NewsletterID" => newsletter.id.to_s,
    "DeliveryID"   => delivery.id.to_s
  }
)

When SES notifies a bounce or complaint via SNS, the payload includes these tags. The reconciler finds the matching EmailDelivery and updates the status:

def reconcile_event(event)
  delivery = find_by_tag(event, "DeliveryID") ||
             find_by_message_id(event)
  return unless delivery

  case event_type(event)
  when "delivery"  then delivery.mark_sent!(message_id)
  when "bounce"    then delivery.mark_bounced!
  when "complaint" then delivery.mark_bounced!
  when "reject"    then delivery.mark_failed!("SES rejected")
  end
end

This closes the loop: even if the delivery stayed as unknown because the worker crashed, SES eventually notifies whether it delivered or not. The reconciler fixes the state.

Pattern 8: Configuration Sets for Monitoring

SES has a feature called Configuration Sets that’s absurdly underused:

params[:configuration_set_name] = ENV["SES_CONFIGURATION_SET"] if configured?

Configuration Sets give you:

• Delivery events: delivery, bounce, complaint notifications via SNS
• Reputation dashboard: real-time bounce and complaint rate
• Sending statistics: volume per hour/day

Without a Configuration Set, you’re flying blind. With it, you know exactly the state of your sender reputation.

Amazon suspends your account if the bounce rate goes over 5% or complaints pass 0.1%. With the dashboard you can see this happening before it’s too late.

Pattern 9: Deferred Sending Report

It’s no use reporting results right after enqueuing. The jobs are still running. The report needs to be deferred:

# Enfileira relatório 30 minutos depois do envio
SendingReportJob.set(wait: 30.minutes).perform_later(newsletter.id)

And the report reschedules itself if many deliveries are still pending:

def perform(newsletter_id, reschedule_count = 0)
  counts = newsletter.email_deliveries.group(:status).count
  pending_ratio = pending_plus_sending / total.to_f

  if pending_ratio > 0.10 && reschedule_count < 3
    # Mais de 10% ainda em andamento — checa de novo em 15min
    self.class.set(wait: 15.minutes)
        .perform_later(newsletter_id, reschedule_count + 1)
    return
  end

  send_report(counts)
end

The final report shows sent/failed/pending/unknown/bounced. If unknown > 0, the color is red — it needs human attention.

The Sandbox Trap

A pain everyone goes through and nobody documents: SES starts in sandbox mode. You can only send to verified emails. To leave the sandbox you need a manual request explaining your use case, estimated volume, and how you handle bounces/complaints.

Tips for approval:

1. Have a verified domain with DKIM — don’t send from @gmail.com
2. Explain double opt-in — “subscriber confirms email before receiving”
3. Show bounce handling — “bounces are automatically processed and removed”
4. Start small — ask for 200/day, scale later

Amazon is paranoid about reputation. Show them you respect that.

DKIM, SPF, and DMARC: The Trilogy That Keeps Your Emails in the Inbox

Without correct DNS authentication, your emails go to spam. Three records are mandatory:

• SPF: declares which servers are allowed to send on behalf of your domain
• DKIM: cryptographic signature proving the email wasn’t altered
• DMARC: policy saying what to do with emails that fail SPF/DKIM

SES generates the DKIM records automatically (three CNAMEs). SPF and DMARC you configure manually in DNS.

If you don’t do this, even Gmail will mark your emails as suspicious. And worse: providers like Microsoft and Yahoo are getting more and more aggressive with emails without DMARC.

Pattern 10: List-Unsubscribe — The Header Gmail Demands

Since February 2024, Gmail has a hard rule for bulk senders (anyone sending more than 5,000 emails/day to Gmail addresses): every email needs the List-Unsubscribe and List-Unsubscribe-Post headers. Without them, Gmail penalizes the reputation of your entire domain — not just the bulk emails, but also transactional ones (like signup confirmation, password reset, etc.).

I found this out the hard way: Gmail users weren’t receiving the subscription confirmation email. DKIM passing, SPF passing, DMARC passing, SES accepting — all green. But Gmail was silently routing to spam because the newsletter didn’t have List-Unsubscribe.

The implementation has two parts: the header in the email and the endpoint that processes the unsubscribe.

The Header

Each email needs two headers — with a URL personalized per subscriber:

mailer.send_email(
  to: subscriber.email,
  subject: title,
  html_body: html,
  headers: {
    "List-Unsubscribe" => "<https://seudominio.com/unsubscribe?token=#{subscriber.unsubscribe_token}>",
    "List-Unsubscribe-Post" => "List-Unsubscribe=One-Click"
  }
)

In SES v2, custom headers go in the headers field of the simple content:

simple = {
  subject: { data: subject, charset: "UTF-8" },
  body: { html: { ... }, text: { ... } },
  headers: headers.map { |name, value| { name: name.to_s, value: value.to_s } }
}

Watch out: the unsubscribe link in the body of the email (the one in the footer) doesn’t count. Gmail specifically requires the HTTP header. These are different things. You need both.

The RFC 8058 Endpoint

When the user clicks “Unsubscribe” in Gmail, what happens isn’t a GET in the browser. Gmail makes a POST directly to your server with the body List-Unsubscribe=One-Click. No cookies, no CSRF token, no redirect.

That means your controller needs to:

1. Skip CSRF verification for that kind of request
2. Return 200 OK instead of a redirect (email clients don’t follow redirects)
3. Keep working normally for unsubscribes via browser

class UnsubscriptionsController < ApplicationController
  # RFC 8058: email clients POST sem CSRF token
  skip_forgery_protection only: :destroy, if: :one_click_unsubscribe?

  def destroy
    subscriber = Subscriber.find_by(unsubscribe_token: params[:token])
    subscriber&.unsubscribe! unless subscriber&.unsubscribed?

    if one_click_unsubscribe?
      head :ok  # Gmail espera 200, não redirect
    else
      redirect_to unsubscribe_path(token: params[:token])
    end
  end

  private

  def one_click_unsubscribe?
    params["List-Unsubscribe"] == "One-Click"
  end
end

The skip_forgery_protection is conditional — it only triggers when the request contains the List-Unsubscribe=One-Click parameter. Regular browser requests still have full CSRF protection.

After implementing this, the domain reputation at Gmail takes 1-2 days to recover. The confirmation emails started arriving in the inbox again.

Pattern 11: The Silent SES Suppression List

SES has a trap that catches a lot of people: the account-level suppression list. When an email hard bounces (nonexistent address) or generates a complaint (marked as spam), SES automatically adds that address to an internal list. From that point on, every time you send to that address, SES accepts the request, returns a message_id, and silently doesn’t deliver.

Read it again: SES returns success, but doesn’t send. Your system thinks it was sent. The subscriber never receives it. No error, no bounce, no log.

To see who’s on the list:

aws sesv2 list-suppressed-destinations --output table

To remove an address (for example, after fixing a deliverability issue):

aws sesv2 delete-suppressed-destination --email-address "usuario@gmail.com"

Careful: don’t go removing everything. If the address bounced because of a typo (usuario@gnail.com instead of @gmail.com), removing it from the suppression list will just generate another bounce — and worsen your bounce rate, exactly what SES monitors to decide whether to suspend your account.

The rule: only remove addresses you have concrete reason to believe are valid. Typos and abandoned addresses stay on the list — SES is protecting you from yourself.

Encrypting Emails at Rest

A detail many ignore: your subscribers’ emails are in the database. If the database leaks, all the emails leak. Rails 8 has native Active Record Encryption:

class Subscriber < ApplicationRecord
  encrypts :email, deterministic: true
end

The deterministic: true is crucial: it lets find_by(email: "x@y.com") work normally, because the same input always produces the same ciphertext. The unique index keeps working. From the application’s point of view, nothing changes — but in the database, the emails are encrypted.

The keys live in environment variables, not in the database. The database leaked? The emails are unreadable without the keys.

The Total Cost

For a newsletter with 1,000 subscribers sending 4 editions per month:

Compare that to Mailchimp ($13/month), ConvertKit ($15/month) or Buttondown ($9/month). The difference is that, with SES, you built the infrastructure instead of renting it. It’s more upfront work, but with zero lock-in and total control.

Conclusion

Sending reliable email isn’t about calling an API. It’s about:

• Per-recipient records with atomic claiming
• Terminal states that are never automatically reverted
• Explicit distinction between “SES rejected” and “SES accepted but something broke”
• Recovery of ambiguous states always to unknown, never to failed
• Deferred reports that reschedule themselves until they have complete data
• Webhook reconciliation that closes the delivery loop
• Correct DNS (DKIM/SPF/DMARC) so you don’t go to spam
• List-Unsubscribe on every email — without it, Gmail penalizes your entire domain
• Awareness of the suppression list — SES may accept and silently not deliver

The golden rule: when in doubt, don’t resend. Better for a subscriber to miss one edition than to receive two. Your domain reputation — and your subscribers’ patience — depend on it.

Update 07/20/2017: I need to clarify a few points. First, I am recommending Cloudinary’s proprietary solution, but there are caveats. You’re trading off ease of use for vendor lock-in. And I only recommend it for photos/images. If you need to upload super-large files (videos, or arbitrary binaries such as big tarballs) you need to research more and perhaps build a custom solution with Shrine or similar. Another statement I make is that if you use Heroku your only option is Direct Upload to Cloud services such as AWS S3. I delivered several apps that did hit the H12 Routing Timeout. It’s in the official documentation. But right now I deployed a simple dumb Rails 5.1 app with vanilla Carrierwave and an HTML form multipart. I was able to upload a 2+GB video file and it went through Heroku’s routing layer. It seems the router picks up the file and lets it finish then passes the finished uploaded file to the Rails app. Now, if you block the request (such as uploading from the Rails app to S3 or doing something else that is time intensive) then the routing layer will H12/timeout the request after 30sec. So you will eventually hit random disconnects if you allow any kind of large file to be uploaded. Even though you can receive it, you can’t keep it in the file system (as it’s volatile in a Heroku Dyno), so you still need to upload it somewhere and that is the part that can hit the timeout. So Direct Upload is still the way to go on Heroku.

DHH just announced a brand new feature for the upcoming Rails 5.2. This is ActiveStorage.

It should become the default solution to support file uploads. It basically supersedes Paperclip, or Carrierwave, or some features of Dragonfly and Shrine (they do a lot more).

I am writing this small post not to introduce the solution but to clarify a few criticisms I made on Twitter. But Twitter is a terrible platform for more in-depth discussions, hence this post.

The original Twitter thread can be found here.

The process has at least 3 important points to consider:

1. The upload of the file, from the end-user to your Rails controller.
2. An optional transformation step (that you should do, to resize images to be served to different devices and screen resolutions)
3. Serving the blob of the file back to the end-user as an image URL, for example.

The Upload Step

Most simple upload solutions - such as ActiveStorage, and old ones such as the original Paperclip and the vanilla install of Carrierwave - basically set the HTML form as a multipart and add a vanilla HTML file field. This will upload the form directly to a Rails controller action, which will receive it in the params hash and you can deal with the binary blob from there.

Naively deployed, this will block the MRI through the entirety of the upload. If the file is very big, it can block any other incoming request for the duration of this upload. (Technically, because Rails supports MRI threads and MRI threads are theoretically non-blocking for IO operations, it shouldn’t be as bad as it sounds.)

Fortunately, I believe no one in their right mind exposes an MRI process directly to the internet. We are usually behind a reverse proxy, such as Haproxy, NGINX, Apache HTTPD or something similar.

And usually those reverse proxies are the ones that receive the upload and they only proxy the request when the upload is finished. So the MRI/Rails application can continue to respond to requests in the meantime.

So, if you have a custom infrastructure, you’re golden.

If you’re using something like Heroku, you’re basically screwed. The Heroku routing layer has a hard timeout of 30 seconds. I consider this a good thing because you shouldn’t have requests that take this long to process. Heck, you shouldn’t have a request responding in 1 second, let alone 30 seconds.

But file upload is the exception. A big file takes time to transfer over the internet. And then the Heroku timeout kicks in and interrupts the transmission. The end-user retries and if you have a large enough crowd, you will start filling up the HTTP queue until you have cascading timeouts over each other.

Which is why the only solution available for Heroku is to do “Direct Upload” to a cloud service such as AWS S3. You can add the Carrierwave Direct add-on, or use a complete 3rd party solution such as Cloudinary, with its client library Attachinary to make things easy. And that’s it!

Active Storage, as it is right now, will work for any good enough custom deploy (NGINX + Rails/Puma) but it won’t work at all over Heroku and when the new branch is finished it will be a good choice to use over Heroku as well.

The Transformation Step

This can be done just after the upload or just before serving the file back to the user.

The first one can be done synchronously or asynchronously.

Synchronously is “bad” (I mean, in the controller action itself, because this step is CPU-intensive and takes time). It’s basically transforming the image (using something like Rmagick or MiniMagick) into other versions of different sizes (thumbnail, mobile version, high-dpi version, etc) and storing the paths to the different versions in the storage.

Asynchronously is deferring this costly transformation to ActiveJob so something like a Sidekiq worker picks it up later and does the processing. Meanwhile, you can serve a placeholder if the particular version is not ready yet.

A caveat is that if you have cloud storage and an asynchronous job transformation, you will have lots of traffic because you will spend time uploading to a cloud storage, then the job will have to download from there, do the transformation and do new uploads.

The other solution is to do no processing whatsoever and defer the processing to be on-demand. This is what 3rd party Cloudinary/Attachinary does and you can do custom transformations using URI parameters. It will make the transformation once and cache the results for future usage. An example of a Cloudinary image transformation URL looks like this:

http://res.cloudinary.com/demo/image/upload/w_400,h_400,c_crop,g_face,r_max/w_200/lady.jpg

This is also what you get if you implement Refile or Shrine. It adds a Rack endpoint to your Rails application that will fetch the image binary, perform the transformation according to the parameters received in the URI, and cache the transformation before sending the binary.

The Serving Step

This is making your Rails app serve the stored blob file. The file can be stored locally (or over a remote NFS mount) or over the internet from any cloud based storage such as AWS S3 (in which case you just link directly to their HTTP endpoint).

When your Rails app serves a local file it can just send a special Header to the reverse proxy (NGINX or Apache - X-SendFile or X-Accel-Redirect, which is the difference between send_file and send_data on ActionController::DataStreaming, by the way) and they will serve the file directly, avoiding locking the MRI for the duration of the file transfer.

If it’s in a cloud storage, it’s even easier because you just print their URL for the file directly in the HTML template and there is zero processing necessary.

You will have some processing if you make Rails read the blob and stream it directly (sometimes you need this because you have restrictive access to the files and you don’t want to risk even using a randomized URL for the file).

Conclusion

DHH is right, Basecamp does serve a lot of files and the ActiveStorage (as well as Paperclip, Carrierwave) works nicely, provided you have a proper NGINX reverse proxy in front of it and you added a proper CDN to cache the files back.

If you don’t want to have to manage your own storage, you should use a Cloud Storage (AWS S3, Google Cloud, Azure, etc). ActiveStorage or other solutions will receive the file in the Rails controller level and you SHOULD use ActiveJob to POST the blob to the cloud service in the background - not blocking your application in the process. But the trade-off is that if you add asynchronous job transformation, you will end up having to fetch the original image from the cloud storage to do the transformations.

You should perform transformations on your images to send the best-sized image back to your end-users. Again, if you do it in your application consider either an ActiveJob worker or the Rack real-time transform-and-cache solutions available from Refile or Shrine. At least as it is right now, ActiveStorage doesn’t provide a solution for the image transformations.

My recommendation of previous blog posts on the subject remains, if this is your first time or your business is just beginning, don’t sweat it. Use a complete solution like Cloudinary/Attachinary. It will take care of everything in the most optimal way.

But this is NOT a definitive recommendation. If you have custom deploys, and you know your requirements and constraints, a solution like ActiveStorage, vanilla Carrierwave, etc works well. There are always trade-offs, and having so many moving parts always adds up complexity. The Cloudinary recommendation is just so you can start with as few moving parts as possible and then move to more complex scenarios later if you need to.

Dealing with all the possible combinations of file upload management is no small feat. And you probably have most pressing concerns in your business logic than dealing with files.

Oh, and repeating the same ol’, same ol’, use a damn CDN already! Regardless of the solution you should always add a CDN to serve your assets (javascripts, stylesheets, images, etc).

I’ve published an article about ExAdmin and Coherence and another on Deploying Elixir to DigitalOcean this month.

The idea is very simple, it is a homage to Pusher. If you used Pusher before, this is very similar (albeit way less feature complete, of course).

I built an entire solution inspired by Pusher, using the Phoenix framework, deployed to Digital Ocean and you can test it out right now, just sign up at expusherlite.cm42.io.

Once you sign up, you will have a secret token (don’t disclose that, of course) and you will be under an Organization. Then you can go on and create Applications within that Organization. Each Application will have a unique token to identify it.

Now, let’s say you want to create a Rails application with a Chat feature. Any version of Rails, you don’t need 5.0 and you don’t need ActionCable.

First off, let’s configure config/secrets.yml:

development:
  secret_key_base: b9a1...e7aa
  pusher_host: "expusherlite.cm42.io"
  org_id: acme-inc
  app_key: 0221...f193
  secret_token: 4036...f193
...
production:
  secret_key_base: <%= ENV["SECRET_KEY_BASE"] %>
  pusher_host: <%= ENV['PUSHER_LITE_HOST'] %>
  org_id: <%= ENV['PUSHER_LITE_ORGANIZATION'] %>
  app_key: <%= ENV["PUSHER_LITE_APP_KEY"] %>
  secret_token: <%= ENV["PUSHER_LITE_SECRET_TOKEN"] %>

Replace the pusher_host, org_id, app_key, and secret_token for the ones you created before.

Now I want to add a PageController:

require "net/http"
require "uri"
class PageController < ApplicationController
  def index
    uri = URI.parse("http://#{Rails.application.secrets.pusher_host}/api/sessions")
    response = Net::HTTP.post_form(uri, {"token" => Rails.application.secrets.secret_token})
    @guardian_token = JSON.parse(response.body)["jwt"]
    Rails.logger.info @guardian_token
  end
end

(If you’re connecting to my online server, you must use SSL, so change the URL above for “https”)

What this piece does is submit the secret token in the server-side, to my service, to get a JSON Web Token (JWT) back. Now you can pass this JWT to the front-end to enable authentication.

In the front-end we can have this simple app/views/page/index.html.erb:

<h1>Ex Pusher Lite - Rails Integration Example</h1>

<script type="text/javascript" charset="utf-8">
  window.guardian_token = "<%= @guardian_token %>";
  window.org_id = "<%= Rails.application.secrets.org_id %>"
  window.app_key = "<%= Rails.application.secrets.app_key %>";
  window.pusher_host = "<%= Rails.application.secrets.pusher_host %>";
</script>

<div id="chat" class="fixedContainer">
</div>

<input type="text" name="name" id="name" value="" placeholder="Name"/>
<input type="text" name="message" id="message" value="" placeholder="Message"/>
<input type="checkbox" name="channel" id="channel" value="api"/>
<label for="channel">send through API</label>

Super simple, we can tweak the CSS (app/assets/stylesheets/application.css) just to make it look nicer:

...
.fixedContainer {
  height: 250px;
  width: 100%;
  padding:3px;
  border: 1px solid black;
  margin: 5px;
  overflow: auto;
}

body {
  font-family: Helvetica, Arial
}

Finally, we need to load the main Javascript from the ExPusherLite server, so edit the layout at app/views/layouts/application.html.erb and add this line right after the closing </body> tag:

<script src="http://<%= Rails.application.secrets.pusher_host %>/js/pusher.js"></script>

And we can now use this Javascript in the app/assets/javascripts/application.js to hook everything up. This is the relevant bit:

$(document).ready(function() {
  var PusherLite = require("pusher_lite").default;

  var pusher = new PusherLite(window.app_key, {
    host: window.pusher_host,
    jwt: window.guardian_token,
    uniqueUserId: "robot" })
    // ssl: true - if you're connecting to my online server

  var publicChannel = pusher.subscribe("general")

  publicChannel.bind("new_message", function(payload) {
    var chat = $("#chat")
    chat.append("<p><strong>" + payload.name + "</strong> " + payload.message + "</p>");
    chat.scrollTop(chat.prop("scrollHeight"));
  })

  pusher.joinAll();

We can now continue in the same file with the Javascript that binds to the message input field, listening to the “Enter” key press event to send the messages:

  var message_element = $("#message");
  message_element.on('keypress', function(event) {
    if (event.keyCode != 13) { return; }

    var name_element    = $("#name");
    var check_element   = $("#channel");
    var payload = { name: name_element.val(), message: message_element.val() };

    if(!check_element.prop("checked")) {
      sendPusher(payload);
    } else {
      sendAPI(payload)
    }
    message_element.val('');
  });

  window.publicChannel = publicChannel;
})

And this is how we send messages to ExPusherLite, either directly through the full-duplex WebSockets:

function sendPusher(payload) {
  console.log("sending through socket")
  window.publicChannel.trigger('new_message', payload );
}

Or Posting to the available API:

function sendAPI(payload) {
  console.log("sending through API")
  $.ajax({
    type : 'POST',
    crossDomain: true,
    url : makeURL("new_message"),
    headers : { Authorization : 'Bearer ' + window.guardian_token },
    data : payload,
    success : function(response) {
      console.log(response);
      console.log("sent through API successfully");
    },
    error : function(xhr, status, error) {
      console.log(error);
    }
  });
}

function makeURL(event) {
  return "http://" + window.pusher_host + "/api/organizations/" + window.org_id + "/applications/" + window.app_key + "/event/" + event;
}

By the way, you can send messages using the API from the server-side if you want. Specifically from an ActiveJob process so you can keep your Rails web application fast, and you can use the opportunity to store the message in your database, or apply any filters.

And this is it! You now have a Rails application with WebSockets. You can have your lunch and eat it too.

If you want to see this example working, I published a demo app over at Heroku. It’s just a demo, it has no authentication, no cross-scripting sanitization, no nothing.

In summary: this is a Rails app (you could do it in Django, Laravel, ASP.NET MVC, it doesn’t matter) talking through WebSocket + APIs to a Phoenix cluster.

Next Steps

Keep following my blog (or my Twitter at @akitaonrails ) for more posts to come.

I am still considering if I will open the ExPusherLite code as open source, so let me know if you’re interested.

I am also considering if I will keep the current servers online as a cheap service. You can use it for free right now to play with it, but don’t use for production-level apps yet. As I am still heavily coding it, I will keep updating the servers, so there is no SLA. Let me know if you’re interested in such a service that keeps the code open source so you can trust it better.

There are important features still missing, such as proper SSL support, encrypted channels, better Presence tracking APIs and so on, but what’s available right now already covers most use cases for WebSockets.

And better: because this is Phoenix, because this is Elixir, and because this is Erlang, we get distributed PubSub for “free”. As I explained in my deployment post, this is a setup with a server in New York and another in London, just to showcase the distributed nature of Erlang.

It’s been very fun to play with Elixir for the past few days and how fast I was able to put together a full-featured solution like this. There were many puzzles that made me scratch my head, figuring out how to deal with cross origin issues, how to make the nodes find each other through the edeliver deployment, figuring out the missing bits in replacing exrm for distillery (which is a transition still taking place in the community), etc.

Now I am quite comfortable with the basics, from bootstrapping a project all the way to deploying in a cluster scenario. And I hope this service proves useful to more people.

As this is possibly my last post of the year: Happy New Year! And I will see you again in 2017!

Cutting straight to the chase, many small Rails apps that I build start with 2 very simple add-ons: Devise for authentication and ActiveAdmin for basic database management. Then I build up from there.

Both Elixir and Phoenix are fast moving targets right now, which makes it difficult for a stable set of libraries to solidify properly, but I think that we’re finally getting past the early adopters curve.

One big point of contention has been user authentication. Many purists will argue that you need to build your own from scratch or by using low level libraries such as Guardian.

If you’re building an application that just exposes API endpoints, that’s probably fine. But for a full-featured web app meant for humans to use, this is hardly a good choice. I will not entertain the discussion today, as it’s beyond the point.

I am assuming that you at least followed both Elixir and Phoenix tutorials by now. If you didn’t go ahead and do it, it will take you one or two days to learn the very basics if you’re already an experienced rubyist. Then come back and read my posts on Elixir to understand where it stands out compared to everything else.

That being said, let’s get started.

Coherence (Devise alternative)

Finally, I found this project that’s been under heavy development for the past 6 months called Coherence. For all intents and purposes, it successfully mimics Devise in almost every way. And this is a very good thing for a lot of scenarios.

Their README is well explained enough so I will not copy and paste it here, just read it there to get up and running. But if you want to try out all of their features you can tweak their procedure with this set of options in the installation Mix task:

mix coherence.install --full --rememberable --invitable --trackable

Run mix help coherence.install to see a description for all the options.

And if you’re not tweaking the front-end, you can just add the proper sign up, sign in, sign out links by adding the following snippet to the web/templates/layout/app.html.eex:

<header class="header">
  <nav role="navigation">
    <ul class="nav nav-pills pull-right">
      <%= if Coherence.current_user(@conn) do %>
        <%= if @conn.assigns[:remembered] do %>
          <li style="color: red;">!!</li>
        <% end %>
      <% end %>
      <%= YourApp.Coherence.ViewHelpers.coherence_links(@conn, :layout) %>
      <li><a href="http://www.phoenixframework.org/docs">Get Started</a></li>
    </ul>
  </nav>
  
</header>
...

(By the way, whenever you see YourApp in the code snippets, you must change it to your app’s module name.)

If you get lost in their documentation you can check out their Coherence Demo repository for an example of a basic Phoenix app with Coherence already configured and working. You will mostly have to take care of web/router.ex to create a :protected pipeline and set the scopes accordingly.

If you do it correctly, this is what you will see:

It’s been a long while since I got excited by a simple sign in page!

Ex Admin (ActiveAdmin alternative)

Then, the next step I usually like to do is to add a simple Administration interface. To that end I found the Ex Admin, that’s been under heavy development since at least May of 2015. It’s so damn close to ActiveAdmin that its old theme will make you forget you’re not in a Rails application.

Again, it’s pretty straightforward to set it up by just following their README instructions.

Once you have it installed and configured, you can very quickly expose the User model into the Admin interface like this:

mix admin.gen.resource User

And we can edit the web/admin/user.ex with the following:

defmodule YourApp.ExAdmin.User do
  use ExAdmin.Register

  register_resource YourApp.User do
    index do
      selectable_column

      column :id
      column :name
      column :email
      column :last_sign_in_at
      column :last_sign_in_ip
      column :sign_in_count
    end

    show _user do
      attributes_table do
        row :id
        row :name
        row :email
        row :reset_password_token
        row :reset_password_sent_at
        row :locked_at
        row :unlock_token
        row :sign_in_count
        row :current_sign_in_at
        row :last_sign_in_at
        row :current_sign_in_ip
        row :last_sign_in_ip
      end
    end

    form user do
      inputs do
        input user, :name
        input user, :email
        input user, :password, type: :password
        input user, :password_confirmation, type: :password
      end
    end
  end
end

Yes, this is eerily similar to the ActiveAdmin DSL. Thumbs up for the team responsible, and it really shows how Elixir is well suited for Domain Specific Languages, if you’re into that.

If you followed the Coherence instructions, it asks you to add a :protected pipeline (a set of plugs) for your protected routes. For now you can add the /admin route to go through that pipeline. And for the uninitiated, a “plug” is similar in concept to a Rack app, or more specifically, a Rails middleware. But in Rails we only have one pipeline of middlewares. In Phoenix we can configure multiple pipelines for different sets of routes (browser and api, for example).

So we can add the following to web/router.ex:

...
scope "/admin", ExAdmin do
  pipe_through :protected
  admin_routes
end
...

With those simple contraptions in place, you will end up with something like this:

And if you’re still not convinced, how about changing to their old theme?

Hell yeah! Makes me feel right at home, although I really prefer the new theme. But you could replace your ActiveAdmin-based app for this one and your users would hardly notice the small differences in the interface. The behavior is basically the same.

If you still have questions on how to properly configure ExAdmin, check out their Contact Demo project, where you can find a real example.

Stitching a simple Admin role

Obviously, we don’t want to let all authenticated users access the Admin section.

So we can add a simple boolean field in the users table to indicate whether a user is an admin or not. You can change your migration to resemble this:

...
def change do
  create table(:users, primary_key: false) do

    add :name, :string
    add :email, :string
    ...
    add :admin, :boolean, default: false
    ...
  end
end
...

And you can configure the priv/repos/seeds.exs file to create 2 users, one admin and one guest:

YourApp.Repo.delete_all YourApp.User

YourApp.User.changeset(%YourApp.User{}, %{name: "Administrator", email: "admin@example.org", password: "password", password_confirmation: "password", admin: true})
|> YourApp.Repo.insert!

YourApp.User.changeset(%YourApp.User{}, %{name: "Guest", email: "guest@example.org", password: "password", password_confirmation: "password", admin: false})
|> YourApp.Repo.insert!

As this is just an exercise, you can drop the database and recreate it, like this: mix do ecto.drop, ecto.setup.

Coherence takes care of authentication, but we need to take care of authorization. You will find many examples online to something that resembles Rails’ Pundit, such as Bodyguard. But for this post I will stick to a simple Plug and create a new Router pipeline.

We need to create lib/your_app/plugs/authorized.ex and add the following:

defmodule YourApp.Plugs.Authorized do
  @behaviour Plug

  import Plug.Conn
  import Phoenix.Controller

  def init(default), do: default

  def call(%{assigns: %{current_user: current_user}} = conn, _) do
    if current_user.admin do
      conn
    else
      conn
        |> flash_and_redirect
    end
  end

  def call(conn, _) do
    conn
      |> flash_and_redirect
  end

  defp flash_and_redirect(conn) do
    conn
      |> put_flash(:error, "You do not have the proper authorization to do that")
      |> redirect(to: "/")
      |> halt
  end
end