It turned out to be much more than that—and in a direction I completely didn’t expect.

What’s inside

The scope is massive. Across 428 pages, Jeremy Evans covers core classes, variable and method design, error handling, code formatting, library and plugin architecture, metaprogramming, DSLs, testing, refactoring, deprecation, design patterns, concurrency, static versus duck typing, and optimization.

Evans is a Ruby committer and the maintainer of Roda and Sequel, so his opinions come with receipts. What I appreciated most is that almost nothing is handed down as an absolute rule. Even the SOLID principles arrive with a warning against applying them dogmatically. Every technique—a plugin system, a DSL, method_missing, static types—is presented as a trade-off. You are expected to decide for yourself, but you get a clear description of what each choice will cost you later. That’s a rarity in programming books.

A lot of the content is highly valuable on its own. But two chapters genuinely stopped me in my tracks because they answered questions I’d been wrestling with all year while building AI features into production Rails apps.

Here are my two highlights.

First highlight: Breaking circuits

This one hit close to home.

Chapter 5 is all about error handling: return values versus exceptions, designing APIs that are hard to misuse, fail-open versus fail-closed, retrying transient errors with backoff, and shaping exception hierarchies. Deep in the chapter, Evans builds a small circuit breaker from scratch: if a service fails three times in a minute, you stop calling it for a while, preventing every request from queuing up behind a provider that’s already down.

Then he closes the section with the exact kind of pragmatic advice I wish more books gave:

“If you need a circuit breaker for production code, you should probably use one of the many circuit breaker gems for Ruby instead of trying to implement a circuit breaker yourself, unless you have specific requirements not handled by an existing gem.”

That is the exact conclusion I reached last year when writing Building a Resilient AI Client in Ruby with Stoplight and ruby_llm for the JetRockets blog. The goal was to detect when a model provider is failing, trip the circuit, fail over to a backup model, and keep the conversation history intact. I went with Stoplight rather than rolling my own, for the exact reason Evans points out.

Still, reading the from-scratch implementation was incredibly useful. You end up understanding exactly what the gem handles for you, and more importantly, what it doesn’t. This chapter also gave me an insight my own article was missing: separating permanent from transient errors is a structural decision that belongs in your exception hierarchy, not in a rescue clause bolted on later. A rate limit and a malformed request are fundamentally different failures, and only one of them deserves a retry. Until now, I’d been treating both simply as “the provider is having a bad day.”

Second highlight: Only mock what you cannot control

The testing chapter drops this rule:

“If you must mock, only mock what you cannot control, such as calls to external APIs.”

For standard HTTP clients, most of us just nod and move on. But try applying that to a feature built around a Large Language Model, and it becomes the definitive answer to a testing problem I’d been circling for weeks.

An AI model isn’t a normal dependency. It’s slow, it costs money on every call, and—the part that really wrecks a test suite—it’s non-deterministic. Same input, different output. This usually leaves you with two bad options. Option A: Mock the entire pipeline, turning your tests into pure theater. They pass forever, asserting only that your own stubs were called, while real regressions walk straight through to production. Option B: Mock nothing, leaving you with a test suite that is flaky, painfully slow, and bills you on every CI run.

Evans’ rule puts the boundary exactly where it belongs. The model provider API is the only thing I cannot control, so it is the only thing I stub. Everything else runs for real: prompt assembly, the batching loop over long content, the context management that keeps terminology consistent across chunks, the state machine of the background job, and saving the final result. If I break the batching logic, a test fails. That’s exactly what tests are for.

I also learned two hard lessons by getting this wrong initially. First, stubbing the client isn’t enough—you also have to pin the exact payload it hands back. Otherwise, the non-determinism just moves one layer down and your assertions start drifting. Second, this testing style severely punishes heavy inline setup. Once I moved the sample AI context into fixtures, the specs became readable and just as fast as any other model test in our suite.

The same chapter states the trade-off plainly, and it’s a quote I’d gladly put on my wall:

“Slower, reliable tests are better than fast tests that break without reason (false positives) and don’t catch actual breakage (false negatives).”

“Zero” hits

Out of curiosity, I eventually ran a search across the entire ebook for the terms “LLM”, “AI”, and “ChatGPT”.

I found exactly one hit: a passing sentence about how users search for library documentation. As a guide for building AI features? Zero hits.

And that is the part I keep coming back to. This isn’t a book about AI, and that is precisely why it helped so much. A model provider is slow, occasionally unavailable, rate-limited, non-deterministic, and entirely outside your control. We already have decades of solid engineering practices for handling dependencies that behave exactly like that.

The only genuinely new thing is that AI failures are more convincing. A broken API simply returns a 503. A broken model returns a fluent, confident, and nicely formatted wrong answer.

The architectural boundary is exactly where it always was. It just matters a lot more now.

Who should read it

Intermediate and senior Ruby developers, without hesitation. If you’re still learning the syntax, learn it somewhere else first—this book assumes you already write Ruby and want to write it better.

And if you maintain any long-lived applications, Chapter 12 earns the read all on its own. Evans argues that features should be treated as liabilities rather than assets, since every single one of them carries a permanent maintenance cost. Therefore, removing a feature is a net gain. It’s the exact same conviction I wrote about a while back regarding removing legacy code, just stated much more sharply than I managed at the time.

Disclosure: Packt sent me a review copy of the book. The opinions here are entirely my own.

Image: “Pas(t)imes in the Computer Lab”, Hanna Barakat & Cambridge Diversity Fund. Better Images of AI, Creative Commons 4.0

The exam consists of 60 multiple-choice questions with a 120-minute limit. The syllabus is divided into five main areas: Agentic Architecture & Orchestration (27%), Tool Design & MCP Integration (18%), Claude Code Configuration & Workflows (20%), Prompt Engineering & Structured Output (20%), and Context Management & Reliability (15%). It tests both theoretical knowledge and practical skills — meaning hands-on experience with Claude and its ecosystem is essential.

Anthropic provides a study guide with recommended resources, including the official documentation and sample questions. Additionally, there are several online courses breaking down the objectives. I did some research, exchanged materials with colleagues also studying for the exam, and here are the resources I found most useful:

1. Official Antrophic courses: video, texts, and quizzes organized into specific learning paths, plus free courses on Claude and AI in general.
2. Claude Architect Foundations Study Guide: the official reference for example questions, in and out-of-scope topics, and exam preparation details.
3. Claude Certification Guide: a non-official website that I’m using to test my knowledge with mock exams and community discussions.
4. Claude Certified Architect - Foundations by freeCodeCamp.org: an excellent crash course video to complement the official materials and help you prepare for the exam.
5. Claude Certified Architect Study Guide (paullarionov): an open-source GitHub repository with a curated guide and additional study materials.

To prepare for the exam, I am not following a rigid, linear plan. Instead, I am dynamically alternating between the four required official courses, reading external articles, and practicing with mock questions. This flexible strategy is very similar to the one I used to pass the Google Associate Cloud Engineer certification some time ago.

That being said, there is a distinct difference between these two exams. The Google Cloud certification is extremely broad — it covers a massive landscape of services, expecting you to understand many topics without necessarily deep-diving into all of them. The Anthropic exam is the opposite. It has fewer main themes, but it requires you to go much deeper into concepts like agentic architecture, prompt engineering, and context management.

Despite this contrast, both exams share the same core philosophy: they are highly contextual. You won’t see questions asking for simple definitions. Instead, they give you a real-world problem and ask for the most appropriate solution.

For example, a typical question for the Anthropic exam looks something like this:

Example Question: You are designing a customer support agent using Claude that needs to check order statuses from a secure internal database. Which approach is the best way to handle this while maintaining security and efficiency?

A) Provide the database credentials in the system prompt so Claude can write and execute SQL queries directly. B) Provide a massive CSV export of the database in the context window. C) Create a Model Context Protocol (MCP) server that exposes a specific get_order_status tool, passing only the necessary parameters. D) Use a generic web-search tool to scrape the internal dashboard.

(The correct answer is C, because it uses the proper architectural pattern for tools and keeps credentials secure outside the model).

This means that simply reading the docs is not enough. You really need to think about the situation and understand why you are choosing a specific architectural pattern.

In the end, preparing for the Claude Architect Foundations is less about cramming documentation and more about adopting an agentic mindset — putting yourself in the shoes of an AI architect who is constantly balancing efficiency, security, and context limits to solve real-world constraints.

Image: Weaving Wires 1 by Hanna Barakat / AIxDESIGN / Better Images of AI, Creative-Commons License.

Going in, I fully expected we’d immediately dive into server clusters, CI/CD pipelines, and configuration files. I’m glad I was wrong. The course actually kicked off with Design Thinking. It forced us to step back from the terminal and discuss the importance of understanding the business problem, the user, and the real-world context before throwing infrastructure at a problem.

To bring these concepts out of the classroom and into reality, I needed a concrete project. I chose running analysis—a domain I know deeply after nine years in the sport. While I already had the core math mapped out in an open-source gem, I wanted to build a complete system to test these operational practices in the wild. The ultimate result of this effort is Calcpace. Recently shipped to production, it is a fully-fledged web application offering running conversions, VO2 max estimates, race calendars, and pace predictions in 15 different languages. Under the hood, it serves as the perfect sandbox for merging backend and ML operations, powered by Ruby on Rails, PostgreSQL, Redis, Sidekiq, Kamal, AppSignal, DigitalOcean, and Cloudflare.

Here are some highlights of how the MLOps principles we studied mapped directly onto this project:

1. Design Thinking and the Cost of an Error: In ML, optimizing a mathematical metric means nothing if it doesn’t solve a user’s problem. For Calcpace, this meant studying existing market solutions and identifying exactly where runners struggle with pace and VO2 max calculations. It echoed the principles of Domain-Driven Design, by Eric Evans—you have to align your software architecture with the business reality. In a running app, a ‘bad prediction’ isn’t just a UI bug; it could mean an athlete pacing a marathon entirely wrong and hitting the wall.

2. TDD as a Pipeline Foundation: We revisited Test-Driven Development not just as a coding habit, but as a critical safeguard. Automated testing is the backbone of both standard software engineering and MLOps. In ML, you don’t just test if the code compiles; you test if the data schema is valid and if the model’s baseline performance holds. Solidifying the test suite for Calcpace was essential to ensure the core math remained completely reliable as new features were added.

3. The “Last Mile” of Model Serving with Rails: Ruby on Rails might not be the default choice for training models, but it is an exceptional tool for the “last mile”—delivering ML insights to the end user. My focus here isn’t on the mathematical training itself, but on building a robust, containerized environment using Kamal. By treating the complex logic (currently encapsulated in the Ruby Gem) as a decoupled service within a Rails/Docker stack, I’m ensuring that when we swap a heuristic for a complex predictive model, the infrastructure won’t blink. Furthermore, managing the latency of serving these predictions within the standard Rails request-response cycle is the real engineering challenge that separates a simple script from a production-ready system.

1. CI/CD and Workflow Automation: Continuous Integration and Deployment are non-negotiable. While the course explored ML-specific tracking tools like Weights & Biases alongside GitHub Actions, I focused on mastering the latter for workflow automation. Every time a new version is released, GitHub Actions runs the test suite and seamlessly triggers a Kamal deployment. It’s a closed loop that ensures the live application is always perfectly synced with the repository.

2. Beyond Uptime (Monitoring Data Sanity): The course introduced the LGTM stack (Looker, Grafana, Tempo, Mimir) for deep observability, which is standard for tracking infrastructure and data drift in ML. For the Calcpace ecosystem, AppSignal paired with Cloudflare serves as our equivalent. It provides fantastic out-of-the-box APM, tracking request latency and error rates. But an MLOps mindset demands more: we must monitor data sanity. If a runner’s VO2 Max prediction suddenly spikes to 99 due to a malformed input, our APM and strict validations help us catch that “silent failure” before it ruins the user’s trust.

3. Lean Infrastructure and Domain Management: We zoomed out to look at infrastructure as a whole—managing VMs, securing CI/CD secrets, and configuring scalable storage. In practice, this also became an exercise in cost efficiency. By leveraging Kamal’s container orchestration, I managed to pack the entire production stack—the Rails app, PostgreSQL database, and Sidekiq for async jobs—into a single $6/month DigitalOcean droplet without sacrificing the ability to scale later. Furthermore, establishing the production environment meant handling the custom .app domain registration and managing DNS and strict SSL configurations through Cloudflare, alongside setting up Cloudflare R2 for cost-effective, S3-compatible object storage.

4. DevOps in an AI-Scraped World: Finally, exposing an API or web app today means dealing with a massive influx of automated traffic. I configured custom WAF (Web Application Firewall) rules to block malicious actors while ensuring the site remains fully accessible to legitimate crawlers. This balance is vital for SEO and for ensuring the content is properly indexed by modern AI search bots.

Ultimately, the final deliverable for this discipline isn’t just a static repository; it’s a living, breathing product. By building Calcpace — and seeing its core open-source gem cross the 10,000 downloads milestone — it reinforced my conviction that a real challenge of a production-ready system lies in reliability, deployment pipelines, and operational monitoring.

Further Reading

• UFRN MLOps Course Repository: The official repository from the MLOps discipline at UFRN. It contains the reference architecture used in our classes, including Python model serving and observability with Kibana.
• How to use Basecamp’s Kamal with AWS and GitHub: A practical guide by JetRockets’ CTO, Igor Alexandrov, on orchestrating container deployments with Kamal and GitHub Actions.
• Continuous Delivery for Machine Learning (CD4ML): core article on applying standard CI/CD and DevOps practices to ML systems.
• Domain-Driven Design by Eric Evans: The foundational book on aligning software models with business reality.

Images: “Running down the shadows” of Vinoth Chandar. Open Verse, Creative Commons 2.0 and MLops (Wikipedia)

Maintaining a consistent UI in a growing Rails application is a classic challenge. We often start with the best intentions, clean HTML and utility classes, but as the app scales, we inevitably fall into “UI boilerplate fatigue.” Whether it’s copy-pasting the same “Avatar with initials” logic across dozens of views or reinventing the wheel for every animated toast, this duplication slowly erodes our development velocity.

To solve this, I recently migrated Calcpace, a running and cycling tracker built with Rails 8, to jet_ui, JetRockets’ component library. In this article, I’ll show you how we used Calcpace as a real-world playground to standardize our interface, leverage Tailwind CSS v4, and solve the production “gotchas” that often come with gem-based assets.

The Problem: Copy-Paste Debt

Before the migration, our UI was functional but repetitive. Handling profile pictures required manual conditional logic for avatars and initials in every view:

<%# Before: UI logic leaking into views %>
<% if current_profile.avatar.attached? %>
  <%= image_tag current_profile.avatar.variant(resize_to_fill: [24, 24]), class: "w-6 h-6 rounded-full" %>
<% else %>
  <div class="w-6 h-6 rounded-full bg-gray-200 flex items-center justify-center text-xs">
    <%= current_profile.initials %>
  </div>
<% end %>

This “inline Tailwind” approach lacks a single source of truth. Changing a border radius meant a tedious search-and-replace across the entire codebase.

The Strategy: Incremental Migration

One of the biggest concerns when adopting a component library is the “big bang” rewrite. Do you have to change every view at once? Absolutely not.

jet_ui is designed for incremental adoption. In Calcpace, we didn’t touch our legacy views initially. We started by replacing the most “noisy” elements—flashes and avatars—and then moved to complex data tables. You can have a page powered entirely by jet_ui components sitting right next to a legacy ERB view using plain Tailwind utility classes. They coexist perfectly because jet_ui respects your existing Tailwind configuration while providing the structure of ViewComponent. This removes the psychological barrier of migration: you can improve your app one component at a time.

Requirements and Plugging in Jet UI

jet_ui is built on ViewComponent and Tailwind CSS v4. It follows a “Rails-native” philosophy, leveraging the latest tools in the ecosystem:

• Ruby >= 3.0 and Rails >= 7.0 (Calcpace runs on Rails 8.1).
• Tailwind CSS v4 (via tailwindcss-rails >= 4.x).
• Stimulus and Turbo (standard in modern Rails).

In your Gemfile:

gem "view_component"
gem "jet_ui"

The Power of Generators

One of jet_ui’s standout features is its suite of generators. They don’t just copy files; they wire up your entire application.

jet_ui:install

This sets up the library in your application (CSS + JS). It is safe to re-run after gem upgrades, as already-configured steps are automatically skipped:

rails generate jet_ui:install

jet_ui:eject

If you need to customize a component beyond standard options, you can “eject” it. This copies the Ruby class, ERB template, and Stimulus controller directly into your app/components/jet_ui/ folder. The ejected files take precedence automatically.

You can eject multiple components at once and use flags to keep your codebase lean:

# Eject button, card, and flash
rails generate jet_ui:eject btn card flash

# Skip specific files if you only want to customize the template
rails generate jet_ui:eject btn --skip-test --skip-preview
rails generate jet_ui:eject flash --skip-javascript

Production Readiness: The Vendoring Strategy

While the install generator works perfectly for local development by pointing to the gem’s path, production environments like Docker or CI require a more portable approach. To ensure a deterministic build and clean logs, we adopt a Vendoring strategy. Instead of relying on absolute filesystem paths that change between environments, we copy the CSS directly into the repository but place it outside the standard Rails asset search path to avoid duplicate serving.

1. Vendor the assets programmatically:

   mkdir -p vendor/stylesheets
   cp -r $(bundle show jet_ui)/app/assets/stylesheets/* vendor/stylesheets/
   

2. Update your Tailwind source file:

   /* app/assets/tailwind/application.css */
   @import "tailwindcss";
   @import "../../../vendor/stylesheets/jet_ui.css";
   

Why this approach?

• Portability: The build works in Docker, CI, and any developer’s machine without modifications.
• Clean Logs: By placing files in vendor/stylesheets (which Propshaft ignores by default), the asset pipeline won’t try to serve individual component files (like popover.css). This prevents the “404 Not Found” noise in production logs for files already bundled into your main CSS.

Customizing the Theme with Tailwind v4

jet_ui uses modern CSS variables. Instead of overriding thousands of utility classes, you update the theme variables in your CSS source:

@theme {
  --accent-hue: 163;      /* Calcpace Emerald */
  --accent-chroma: 0.2;
  --accent-lightness: 0.52;
}

Every component, from buttons to focus rings, will now use your custom palette.

Replacing the Noise: Real-World Examples

Interactive Form Groups

We used jet_ui.group to standardize selectors. For our activity unit toggle (KM/MI), the component handles the styling and layout, leaving us with a clean DSL:

<%= jet_ui.group do %>
  <%= form.radio_button :unit, "km", checked: true %>
  <%= form.radio_button :unit, "mi" %>
<% end %>

Advanced Composition: Tables and Tabs

The World Records page was our “stress test” for displaying dense data. By composing tabs, card, and table, we reduced a complex view to a readable DSL:

<%= jet_ui.tabs do %>
  <%= jet_ui.tabs_item "KM", href: records_path(unit: "km"), active: @unit == "km" %>
  <%= jet_ui.tabs_item "MI", href: records_path(unit: "mi"), active: @unit == "mi" %>
<% end %>

<%= jet_ui.card class: "overflow-hidden" do %>
  <%= jet_ui.table hovered: true do %>
    <%= jet_ui.table_thead do %>
      <%= jet_ui.table_tr do %>
        <%= jet_ui.table_th { "Event" } %>
        <%# ... %>
      <% end %>
    <% end %>
  <% end %>
<% end %>

This composition proves the architectural leverage: we get a professional data grid with integrated navigation, all following the same design system with zero manual CSS.

Why jet_ui? (The Alternatives)

You might ask: “Why not just use Flowbite, shadcn-rails, or RailsUI?”

While those are great tools, they occupy different niches. Flowbite is fantastic for Tailwind-first projects but isn’t built as a first-class ViewComponent library, often requiring you to wrap their HTML yourself. shadcn-rails follows the “copy-paste” philosophy which is great for total control, but lacks a clean, gem-based upgrade path for those who want their design system managed as a dependency. RailsUI is a premium, template-oriented solution that is excellent for rapid prototyping but might feel too opinionated for existing apps.

jet_ui sits in the “Goldilocks” zone: it’s ViewComponent-native, Tailwind v4-native, and gem-distributed with an “eject-on-demand” safety valve. You get the maintenance benefits of a gem with the flexibility of local code when you need it.

Conclusion: Architectural Leverage

Migration isn’t just about “fancy” code. It’s about reducing cognitive load. Developers can focus on building features using high-level components rather than wrestling with low-level utility classes in every single view. If you’re building a modern Rails app, jet_ui is the bridge between the flexibility of Tailwind and the structure of a professional design system.

Links

• 📦 Jet_UI on RubyGems
• 📁 Jet_UI Repo
• 🏃 Calcpace

The calcpace gem is a pure Ruby library — no I/O, no Rails, no external dependencies. Every formula lives in its own module, included into the main Calcpace class. The site consumes it as a regular gem dependency; when a new module ships, the site updates the Gemfile and builds on top of it. Since v1.8, three modules were added.

CameronPredictor — an exponential race prediction formula that runs alongside the existing Riegel predictor (T2 = T1 × (D2/D1)^1.06). Cameron tends to be more conservative than Riegel for shorter base distances, which matters when you’re predicting a marathon from a 5K time. Having both lets you compare and pick the more realistic estimate for your training context.

TrackCalculator — GPS math: Haversine distance between coordinate pairs, cumulative elevation gain, and per-km splits from an array of raw trackpoints. Pure calculation — no map rendering, no file parsing. The module receives coordinates and returns numbers; the site handles everything else.

Vo2maxEstimator — Daniels & Gilbert formula. Given a race time and distance, returns an estimated VO2max and a fitness classification (from “Poor” to “Elite”). The gem API convention applies here: inputs use symbols (:km, :mi), outputs are always strings — never symbols.

The GPS flow on the site: when a user uploads a GPX file, Active Storage saves it to Cloudflare R2 and enqueues GpxParseJob to Sidekiq. The job runs GpxParser, which extracts trackpoints (lat, lon, elevation, time), then calls TrackCalculator from the gem to compute distance, elevation gain, and splits. Trackpoints are persisted and the activity is updated with the computed stats. The map renders with Leaflet.js and OpenStreetMap tiles — no API key, no vendor lock-in, no usage limits.

Moving from invite-only to open registration meant adding real bot protection. The approach: Cloudflare Turnstile on the registration form, Rack::Attack for rate limiting at the Rails level. Turnstile was straightforward to integrate, with two gotchas that cost more time than expected. The widget script URL uses /v0/, not /v1/ — the docs aren’t always consistent about this. And the form param is cf-turnstile-response (hyphens), not cf_turnstile_response (underscores) — Rails’ params hash keeps hyphens, so the usual convention doesn’t apply. There’s also a pending issue: when the registration form reloads after a validation error, Turbo replaces the DOM but doesn’t re-initialize the widget, so the next submission fails silently. The fix is re-initializing after a Turbo render — still pending.

For file storage, Active Storage with Cloudflare R2 as the backend handles avatars, activity photos, and GPX files. S3-compatible, free egress within Cloudflare’s network, no CDN configuration needed.

Rails 8 ships generates_token_for as a first-class model API for signed, expiring tokens. The email verification flow uses it: on registration a token is generated with 48h expiry, the verification email includes a signed URL, and unverified accounts are blocked from logging in with a resend option shown. The verification email is HTML now — styled with a button and a copyable fallback link. Before this it was plain text, which looked unfinished for an open product. Transactional emails go through Resend API; the password reset flow was already using it and verification plugged into the same setup.

Every user gets a public profile at calcpace.app/:username — avatar, bio, city, country, and activity feed. Each activity has an individual public boolean: toggle it on the activity form and it appears or disappears from the public feed immediately. Activities can also have a photo attached. Your profile page only shows what you choose to share.

The clearest architectural decision in this project: the gem does pure calculation, the site does I/O. No file parsing in the gem, no HTTP, no database. This makes the gem testable in isolation (Minitest, no Rails required) and keeps the site thin — controllers call gem methods and persist results, nothing more. The delivery sequence is always: implement module in gem → write tests → publish new version → update Gemfile in site → build the UI on top. GitHub Actions publishes to RubyGems automatically on version bump in lib/calcpace/version.rb.

What’s next: internationalization first — the app is English-only for now, but the i18n infrastructure is already in place. Adding PT-BR, Spanish, German, and French means auditing hardcoded strings, migrating GpxParser error messages to i18n keys, and translating the emails. Then content pages: pace conversion tables, race equivalent tables, Boston qualifying times, world records. Mile splits in the activity view are also coming — the gem already supports it via track_splits(points, 1.609), the UI just needs a toggle. Strava and Garmin direct connection is planned — GPX import already works for the manual export flow, the next step is OAuth2 for automatic sync.

• calcpace.app
• calcpace gem on RubyGems
• calcpace_web on GitHub

Image: “BP Running Track @ Glasgow Airport” by JCDecaux Creative Solutions. Open Verse, Creative Commons BY-NC-ND 2.0

The core logic for this project has actually been brewing in my head for about five years. Combining my daily routine as a runner with the logic I apply professionally when building delivery and routing systems, it just made perfect sense to model pace, distance, and time mathematically. I eventually sat down and started writing the core Ruby code four years ago, which evolved into the open-source gem.

When the gem crossed the 7k mark, I realized it was time to make it accessible to non-programmers.

The app provides a suite of free running tools: pace, speed, finish time, split breakdowns, and a race predictor using both the Riegel and Cameron formulas. The converter covers 30 combinations across distance, speed, and pace—km, mi, meters, yards, feet, knots—all easily switchable between metric and imperial systems.

I didn’t want it to be just another “enter your numbers” calculator. There are dedicated guide pages explaining the math behind each formula. For instance, you can read about why the Cameron predictor tends to be more conservative than Riegel for shorter base distances, and what that actually means for your training blocks.

From planning to writing the code and setting up the infrastructure, the web version took me about four days. I used this as an opportunity to build with a modern, pragmatic stack:

• Ruby on Rails 8: The foundation of the app. It provides a solid structure and allows me to practice “dogfooding” by consuming my own gem in a production environment. The gem does all the heavy lifting for the calculations, keeping the Rails controllers incredibly clean.
• The Basecamp Way: I treated this project as a playground to strictly follow 37signals’ design principles. That means pushing the logic down to rich models, keeping controllers thin, and leveraging Current attributes to handle global state cleanly.
• Tailwind CSS: To keep my focus on the backend and infrastructure, I used Tailwind to rapidly build a clean, responsive interface without writing custom CSS files.
• Testing & CI/CD: Since this serves as a live environment for the gem, reliability is key. The app is fully tested with Minitest, and GitHub Actions runs the CI/CD pipeline on every push to main.
• Kamal & VPS: I wanted to step away from traditional, expensive PaaS solutions. I deployed the application using Kamal, which packages the Rails app into Docker containers and handles zero-downtime deployments directly to a DigitalOcean Virtual Private Server (VPS).

Take it for a spin

While the personal activity tracker (run/ride logging) is technically in closed testing, I built a sandbox and share with some friends so they can explore the UI and see the gem working in a real database environment.

To keep things tidy, a GuestResetJob runs via sidekiq-cron to wipe the guest activities and recreate the sample profile every Monday at 3 AM.

What’s Next

The engine is running smoothly, but there’s more to come. I am currently working on adding VO2max, VDOT, and training zone calculations—these will be introduced as new modules in the gem and will get their own guide pages on the site.

Links:

• calcpace.app
• calcpace gem
• GitHub repo

Traditional keyword search is fundamentally limited—it can only match exact words or their basic variations. Search for “customer pain points” and you’ll miss documents titled “User Frustrations” or “Client Challenges,” even though they’re semantically identical. This limitation becomes critical when managing large document repositories where users need to find information based on meaning, not memorized keywords. The solution is semantic search using vector embeddings, which represent text as mathematical vectors that capture conceptual similarity. In previous articles, we explored how ruby_llm simplifies working with AI providers for function calling and resilient architectures. Now we’ll leverage ruby_llm’s embedding capabilities to build semantic search with PostgreSQL’s pgvector extension—creating a system that finds “churn analysis” when users search for “why customers leave.”

What Are Vector Embeddings?

Think of vector embeddings as a way to translate text into the language of mathematics—or as some describe it, “searching by vibes” rather than exact keywords. Each piece of text becomes an array of numbers (a “vector”) where similar meanings produce similar numbers. The embedding model has learned, through training on billions of texts, that certain concepts cluster together in this mathematical space.

We’ll use OpenAI’s text-embedding-3-small (1,536 dimensions) for its solid performance-to-cost ratio, but ruby_llm also supports other models: Gemini’s text-embedding-004 (768 dimensions), Voyage AI’s models, or even local alternatives like all-MiniLM-L6-v2 via Ollama for privacy-sensitive applications. The choice depends on your budget, latency requirements, and whether you prefer cloud or self-hosted solutions.

For example:

• “customer churn analysis” → [0.234, -0.891, 0.456, ...]
• “user retention study” → [0.221, -0.883, 0.449, ...] (very close!)
• “quarterly revenue report” → [-0.678, 0.234, -0.123, ...] (very different)

When a user searches for “why are customers leaving”, the system converts this query into a vector and finds documents with similar vectors—automatically surfacing reports about “churn factors” and “cancellation reasons” without requiring exact keyword matches.

Setting Up ruby_llm for Embeddings

Just as we used ruby_llm for function calling in our previous article, we can use it for embeddings too. The gem provides a unified interface with consistent error handling and automatic retries:

# config/initializers/ruby_llm.rb
require "ruby_llm"

RubyLLM.configure do |config|
  config.openai_api_key = Rails.application.credentials.dig(:openai, :api_key)
end

# Create a reusable client instance
LLM_CLIENT = RubyLLM

Now create a wrapper that handles the embedding API calls:

# app/services/embedding_service.rb
class EmbeddingService
  MODEL = "text-embedding-3-small"
  DIMENSIONS = 1536

  def self.embed(texts)
    texts = Array(texts)
    return [] if texts.empty?

    # ruby_llm handles the API call automatically
    result = LLM_CLIENT.embed(texts, model: MODEL, dimensions: DIMENSIONS)
    result.vectors
  end
end

That’s it! Using ruby_llm gives us the same benefits we saw in the function calling article: provider abstraction, automatic error handling, and consistent behavior across different AI services.

Setting Up pgvector for Storage

Why pgvector? If you’re already running PostgreSQL (and many Rails apps are), pgvector lets you store and search vectors without adding new infrastructure. No separate vector database to maintain, no data synchronization issues, and transactions work normally—your embeddings live right next to your application data. The pgvector extension adds specialized vector types and HNSW indexing for sub-100ms similarity searches across millions of vectors.

Before storing embeddings, enable the extension:

# db/migrate/create_documents.rb
class CreateDocuments < ActiveRecord::Migration[8.0]
  def change
    enable_extension "vector"

    create_table :documents do |t|
      t.string :title, null: false
      t.text :content, null: false
      t.references :user, null: false, foreign_key: true
      t.timestamps
    end

    create_table :document_chunks do |t|
      t.references :document, null: false, foreign_key: true
      t.integer :chunk_index, null: false
      t.text :content, null: false
      t.vector :embedding, limit: 1536
      t.timestamps
    end

    # HNSW index for fast nearest-neighbor search
    add_index :document_chunks, :embedding, using: :hnsw, opclass: :vector_l2_ops
  end
end

The HNSW (Hierarchical Navigable Small World) index creates a graph structure that allows fast approximate nearest-neighbor search—essential for sub-100ms queries across thousands of vectors.

Basic Pattern: Chunking Documents

Here’s the challenge: documents can be very long, but embedding models work best on focused text segments (500-2000 characters). Embed an entire 50-page document and you’ll get a diluted embedding that doesn’t capture nuances. The solution is chunking with overlap. The overlap (typically 10-20%) prevents losing context at boundaries:

# app/models/document.rb
class Document < ApplicationRecord
  CHUNK_SIZE = 1_000
  OVERLAP_SIZE = 200

  has_many :document_chunks, dependent: :destroy

  def generate_chunks!
    step = CHUNK_SIZE - OVERLAP_SIZE
    chunks = []

    # Split content into overlapping chunks
    0.step(content.length - 1, step) do |offset|
      chunk = content[offset, CHUNK_SIZE]
      chunks << chunk if chunk.present?
    end

    return if chunks.empty?

    # Generate embeddings for all chunks in one call
    embeddings = EmbeddingService.embed(chunks)

    ActiveRecord::Base.transaction do
      document_chunks.destroy_all

      chunks.zip(embeddings).each_with_index do |(chunk, embedding), index|
        document_chunks.create!(
          chunk_index: index,
          content: chunk,
          embedding: embedding
        )
      end
    end
  end
end

Notice how we generate embeddings for all chunks in a single call. Instead of making 50 separate API requests for a 50-chunk document, we make just one. The ruby_llm gem handles the batching automatically, just like it does with function calling.

The character-based approach above works, but cutting mid-sentence degrades semantic meaning. A better strategy splits on sentence boundaries using text.scan(/[^.!?]+[.!?](?:\s+|$)/), accumulating sentences until reaching the size limit. This preserves complete thoughts while maintaining consistent chunk sizes—particularly valuable for technical documentation where sentence context matters.

Advanced Pattern: Hybrid Scoring (Semantic + Temporal)

Pure semantic search has a problem: outdated documents with perfect semantic matches outrank recent documents with good matches. When users search for “current market size”, they might get a 2023 report instead of the fresh 2025 one. The solution is hybrid scoring—combine semantic similarity (70%) with recency (30%):

# app/models/document_chunk.rb
class DocumentChunk < ApplicationRecord
  belongs_to :document
  has_neighbors :embedding, dimensions: 1536

  attr_accessor :search_score

  def self.search_by_semantics(query, user:, limit: 20, threshold: 0.8)
    # Convert query to embedding using ruby_llm
    query_embedding = EmbeddingService.embed(query).first

    # Get more candidates than needed for scoring
    neighbors = joins(:document)
                  .where(documents: { user: user })
                  .nearest_neighbors(:embedding, query_embedding, distance: "cosine")
                  .limit(limit * 5)

    # Calculate hybrid scores
    scored_neighbors = neighbors.map do |chunk|
      semantic_similarity = 1 - (chunk.neighbor_distance / 2.0)
      recency_score = calculate_recency_score(chunk.created_at)

      # 70% semantic, 30% recency
      chunk.search_score = (semantic_similarity * 0.7) + (recency_score * 0.3)
      chunk
    end

    # Filter and return top results
    scored_neighbors
      .select { |c| c.neighbor_distance < threshold }
      .sort_by { |c| -c.search_score }
      .first(limit)
  end

  def self.calculate_recency_score(created_at)
    age_in_days = (Time.current - created_at) / 1.day
    return 1.0 if age_in_days <= 30  # Recent: full score
    return 0.7 if age_in_days > 365  # Old: 30% penalty
    1.0 - ((age_in_days - 30) / 335.0) * 0.3  # Linear decay
  end
end

The key insight: we fetch limit * 5 candidates first, then score and filter. Why? A chunk might be the 50th-best semantic match but jump into the top 5 after adding recency. By casting a wider net initially, we don’t miss valuable recent documents.

Putting It All Together

Now let’s see the complete flow from upload to search:

class DocumentsController < ApplicationController
  def create
    document = current_user.documents.create!(
      title: params[:title],
      content: params[:content]  # or extract from uploaded file
    )

    # Generate chunks and embeddings asynchronously
    GenerateEmbeddingsJob.perform_later(document.id)

    render json: { id: document.id, status: "processing" }
  end

  def search
    results = DocumentChunk.search_by_semantics(
      params[:query],
      user: current_user,
      limit: 10,
      threshold: 0.75
    )

    render json: {
      query: params[:query],
      results: results.map do |chunk|
        {
          document_title: chunk.document.title,
          excerpt: chunk.content[0..300],
          relevance_score: chunk.search_score.round(2)
        }
      end
    }
  end
end

The architecture is completely asynchronous where it matters. Document uploads don’t block waiting for embeddings—users get immediate feedback, and embeddings are generated in the background. Meanwhile, searches are fast (typically under 100ms) because pgvector’s HNSW index does the heavy lifting.

Advantages of This Approach

The benefits go far beyond “better search.” The system demonstrates semantic understanding—users can search for “why customers switch providers” and find reports titled “Competitive Migration Patterns,” even though those exact words don’t appear in the query.

From an engineering perspective, the architecture is production-ready: context preservation through overlapping chunks means no information is lost at boundaries, temporal awareness via hybrid scoring ensures recent insights aren’t buried, and ruby_llm provides the same advantages we explored in previous articles—automatic retry logic, consistent error handling, and clean abstractions for AI interactions.

When to Use Semantic Search

Semantic search shines when users need to find documents by meaning rather than exact keywords—scenarios like customer support knowledge bases, research archives, or legal document discovery where synonyms and conceptual similarity matter. It’s especially valuable powering AI features: chatbots citing documents, assistants surfacing relevant research, or agents (using ruby_llm’s function calling) that search intelligently.

However, skip it for small document sets (<100 documents) with well-structured content, cases requiring exact phrase matching (legal contracts), or real-time updated content where the 1-2 second embedding latency is problematic. Traditional keyword search with proper indexing often suffices for simpler use cases.

Best Practices

Through implementing semantic search systems, several best practices have emerged:

Always Use Overlapping Chunks: The 200-character overlap prevents context loss at boundaries. Resist the temptation to eliminate overlap to save on storage—it’s a false economy that degrades search quality.

Batch Your Embeddings: Generate embeddings for all chunks in a single call to EmbeddingService.embed(chunks). Process 20-chunk documents with one request instead of 20, reducing latency by 95% and API costs proportionally.

Tune Thresholds Per Use Case: The 0.8 default threshold works for most cases, but use 0.85 for mission-critical searches (where precision matters) and 0.75 for exploratory searches (where recall matters). Monitor your analytics and adjust accordingly.

Async Everything That Can Be Async: Never block user requests waiting for embeddings. Generate them in background jobs and show a “processing” indicator. Users can continue working while documents are indexed.

Conclusion

Transitioning from keyword-based to semantic search transforms how users interact with your data, and as we’ve seen, it doesn’t require adopting entirely new infrastructure. By keeping our architecture resilient with PostgreSQL and pgvector, we avoided the overhead of maintaining a separate vector database. We then used ruby_llm to abstract the complexity of interacting with AI providers, ensuring our API calls are batched and fault-tolerant.

Finally, we solved the real-world UX challenges of AI search by implementing overlapping text chunks to preserve context, and hybrid scoring to balance semantic accuracy with temporal relevance. The magic of modern AI tools in the Rails ecosystem is that they allow us to build highly sophisticated features—like “searching by vibes”—while relying on the same pragmatic, robust engineering principles we use every day.

Additional Resources

• 📄 Embeddings: What they are and why they matter by Simon Willison
• 📄 What are embeddings? by Vicki Boykis
• 📁 pgvector GitHub Repository
• 📁 neighbor gem for Rails
• 📁 ruby_llm gem on GitHub

Image: “Word Search” by Morgan Frederick. Open Verse, Creative Commons 2.0

Originating in law and business, “Due Diligence” refers to the comprehensive appraisal of a business or situation prior to signing a contract. It is the rigorous investigation required to ensure that all parties know exactly what they are getting into, minimizing risks and surprises. In an era where AI can plan, code, and review faster than ever, our responsibility to verify increases. We must be prepared to take full ownership of the results and evaluate precisely what we are delivering.

In Software Engineering, we can apply this concept to the daily “contracts” we make: the code we ship to production and the questions we ask our colleagues. It is about applying rigor, context, and documentation to the acts of coding and asking.

To ensure that we are not just “task-completers,” but intentional engineers, I propose applying this personal audit before every task.

Phase 1: The Build Checklist (Coding with Context)

Before writing a single line of code, understand exactly what you are getting into.

The “Why”

[ ] Business Goal: Do I truly understand the user problem or business value this task resolves? If I can’t explain why a feature exists, I am not ready to code it.

Software Archaeology

[ ] Pattern Matching: Have I searched for similar features already implemented in the project? Reusing existing patterns ensures consistency.

[ ] External References: If no internal pattern exists, did I research reliable external sources and adapt them to our specific context?

[ ] Architectural Decisions: Have I studied why the current code is written this way? I need to understand the legacy choices before I can introduce new ones.

The Blueprint

[ ] Integration: How will the solution plug into the existing project?

[ ] Harmony: Will the approach clash with the codebase’s style? Most of the time goal is for the code to look like it has always belonged there.

💡 The Innovation Caveat: Sometimes, the goal is to break the pattern. Companies hire engineers to think and act, not merely to reproduce—that is how technical diversity and evolution happen. However, swimming against the current requires stronger muscles. If you deviate from the established architecture, your “Due Diligence” must be doubled. Be prepared to defend why the new approach is necessary and superior.

The Self-Audit

[ ] Goal Check: Does the solution actually solve the initial problem?

[ ] Quality Control: Is the code clean, documented, and compliant with project standards?

[ ] Monitoring & Safety: How will I detect possible problems in production? Do I have a plan to revert changes if necessary?

Phase 2: The “Unstuck” Checklist (Asking with Purpose)

Sometimes, despite our best efforts, we hit a wall. Let’s reflect a little before reaching out for help.

The Solo Mission (Before Asking)

[ ] Consult the Documentation: Have I actually read the manual and READMEs?

[ ] The External Search: Have I checked Stack Overflow or forums for similar errors?

[ ] The Git History: Have I run a git blame to see if a recent change caused the issue?

The Evidence Package (Formulating the Question)

When reaching out to a peer, you shouldn’t just ask for the solution; you must present your findings.

Contextualize: “It’s not working” is not a question. I must explain the specific gap between expectation and reality. Document the Journey:

• “I tried X, hoping for Y, but got Z.”
• “I looked at the docs for library A, but they seem outdated.”

By documenting the effort, we prove respect for the team’s time. You are not asking them to do the work; you are asking them to unblock the specific obstacle you couldn’t clear yourself.

The Result: A Compass, Not a Cage

In the reality of our daily work—filled with calls, tight deadlines, and urgent bug fixes—I don’t religiously check every box for every single commit. That would be paralyzing.

Instead, I keep this checklist within eyesight. It serves as my anchor.

When everything is flowing, I might skip a step. But when I feel stuck, when the solution isn’t clear, or when I simply run out of ideas, I return to these lists. They force me to pause, breathe, and realign with the process. The idea follows a simple principle: autonomy isn’t about being perfect all the time; it’s about knowing where to look when you get lost.

Image: “Compass” by Johannes Ko. Open Verse, Creative Commons 2.0

It boasts beautiful beaches, dunes, wind, marvelous food, and a strategic position as one of the closest points in the Americas to Africa and Europe. The area was originally inhabited by the Potiguar indigenous people. Then, during the Age of Discovery, the Portuguese established a fort and a city. After some decades, it passed into Dutch hands before returning to the Portuguese until Brazil’s independence. During World War II, this was considered one of the four most strategic places in the world, hosting the largest airbase for the Allies. However, today is not a day to talk about wars.

Over time, this city has embraced diverse Christmas traditions. The end of the year is the height of Summer in South America, so forget winter clothes and snow; imagine beaches and parties with happy people. But some traditions remain. Natal has a Christmas tree made of light that is 20 meters taller than the Statue of Liberty in New York. It illuminates the night with dynamic, ever-changing colors in a city that has been Christmas every day for the last four centuries.

For my final project in IMD3002 - Supervised Machine Learning at Artificial Intelligence program at UFRN, instructed by Prof. João Carlos Xavier Junior, I didn’t just trained models. We build a complete, rigorous scientific framework to test the fundamentals of Machine Learning.

Here is how I broke down the workflow into a series of sequential experiments.

The Objective

The goal was to classify images of specific breeds (Miniature Pinscher/English Setter vs. Birman/Ragdoll) by exercising every fundamental stage of a classic ML pipeline: from raw pixels to statistical validation.

Step 1: Feature Extraction (Beyond Pixels)

Raw images are noisy and high-dimensional. To make them digestible for classical algorithms, I implemented two distinct visual descriptors:

• HOG (Histogram of Oriented Gradients): To capture the shape and edge structures.
• LBP (Local Binary Patterns): To capture the texture of the fur.

Step 2: Dimensionality Reduction

With high-dimensional feature vectors, the “Curse of Dimensionality” becomes a real threat. I applied PCA (Principal Component Analysis) to project the data into a lower-dimensional space, balancing computational efficiency with information retention.

Step 3: Model Training & Tuning

I implemented and compared five distinct classes of algorithms to see how they handled the visual data:

• k-NN: Instance-based learning.
• Naive Bayes: Probabilistic modeling.
• Decision Trees: Rule-based learning.
• MLP (Multi-Layer Perceptron): Neural Networks.
• Ensembles: Random Forest, AdaBoost, Voting, and Stacking.

Each model underwent rigorous hyperparameter tuning (GridSearch) to ensure we were comparing the best versions of each.

Step 4: Statistical Evaluation

This is where many projects stop, but scientific rigor requires more than just comparing average accuracy. I applied the Friedman Test to determine if the differences in performance were statistically significant and the Nemenyi Post-hoc Test to pinpoint exactly which models outperformed the others.

The Verdict

The statistical analysis revealed that for this specific dataset, an MLP combined with LBP features offered the best trade-off between predictive power and computational cost, significantly outperforming shape-based approaches (HOG).

You can explore the full step-by-step workflow, organized in sequential Jupyter Notebooks, on my GitHub: https://github.com/0jonjo/cat_dog_ml

Image: “Ai is… Banner”, Rick Payne and Team. Better Images of AI, Creative Commons 4.0