Forem: Alexander Shagov

How LLM users accidentally do TDD without realizing it

Alexander Shagov — Sat, 10 May 2025 07:24:54 +0000

Most developers using LLM tools today are unknowingly following a loose version of test-driven development (TDD).

1. TDD and LLM prompting work surprisingly similar

a) Start with failure

TDD: You define an interface and write a failing test first. Now you know what needs fixing.
LLMs: You write a vague prompt, get bad results, and think "I need to explain this better." Same basic concept.

b) Make it work

TDD: You write code until the test passes.
LLMs: You tweak the prompt, add details, and retry until you get good output. Same iterative approach.

c) Clean it up

TDD: "Okay, now let's clean this up."
LLMs: "This works but looks messy - needs polishing." Same final step.

2. Why developers end up doing TDD-like work with LLMs

Many developers claim to hate TDD ("too much overhead!") but end up doing something similar because:

They have to think through requirements first (or the AI won't help)
They iterate repeatedly (just with prompts instead of tests)
They refine the AI's output (which is rarely perfect on first try)

3. LLMs reveal who actually understands coding

Beginners: Ask AI → Copy → Paste → Breaks → Gets stuck
Experienced devs: Plan → Experiment → Debug → Verify results

This mirrors TDD:

Weak developers write tests that don't actually help
Strong developers write tests that improve code and serve as documentation

The irony

If you avoid TDD but use LLMs... surprise! You're basically doing TDD-ish style of work without calling it that.

TDD is structured (test → fail → code → refine)
LLM prompting is more ad-hoc (ask → adjust → accept → maybe improve later)

What this shows us

Skilled developers use LLMs like TDD - they plan, test, and refine.
Junior developers use LLMs like supercharged Stack Overflow - copy, paste, and pray.

In the end, any tool just amplifies your existing thought process.

Configuring your own deep research tool (Using Nix Flakes)

Alexander Shagov — Mon, 28 Apr 2025 15:48:44 +0000

So, you've come across deep search tools and are wondering if you can build your own. Well, you certainly can! Building one yourself might involve tasks like scraping web URLs, implementing your own RAG (Retrieval-Augmented Generation) system to find relevant information, and then summarizing it using an agent loop.

Luckily, the open-source community has already created tools that handle many of these steps. The purpose of this article is to demonstrate how easily we can spin up the necessary environment for such a tool using Nix. We'll focus not only on running the service, but also on development environment setup, making it easy to modify the tool if needed.

For demonstration purposes, I'll be using the gpt-researcher tool.
Github link: https://github.com/assafelovic/gpt-researcher

The basic setup for almost any Python project often feels trivial: install Python, install requirements.txt, and you're good to go. However, if you manage tens of these projects on your machine, you'll quickly realize you not only need to isolate your project environments (which .venv solves) but ideally also isolate the Python installations themselves.

Welcome Nix flakes!

Why Use Nix for Your Development Environment?

Nix is a powerful package manager that helps ensure your development environment is reproducible and isolated. By defining your dependencies (like Python and other tools) in a Nix flake, anyone (including your future self!) can recreate the exact same environment with a single command, avoiding "it works on my machine" problems.

To get a better grasp of what Nix is, you can check out my beginner's article.

Nix flake

Once you pulled the repo, the only thing you need to do (besides .env configuration with your own API keys), is to setup the dev environment using a nix flake. Here's what my file looks like:

{
  inputs = {
    nixpkgs.url = "nixpkgs";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs {
          inherit system;
          config.allowUnfree = true;
        };
      in {
        devShells.default = pkgs.mkShell {
          buildInputs = with pkgs; [
            git

            python311
            python311Packages.pip
            python311Packages.virtualenv
          ];

          shellHook = ''
            # Create and activate virtual environment if it doesn't exist
            VENV=.venv
            REQUIREMENTS_HASH=".venv/.requirements.hash"

            # Calculate new hash of requirements file
            NEW_HASH=""
            if [ -f "requirements.txt" ]; then
              NEW_HASH=$(sha256sum requirements.txt)
            fi

            if [ ! -d "$VENV" ]; then
              echo "Creating virtual environment..."
              python -m venv "$VENV"
              source "$VENV/bin/activate"

              # Initial pip upgrade and requirements installation
              pip install --upgrade pip
              if [ -f "requirements.txt" ]; then
                echo "Installing requirements from requirements.txt..."
                pip install -r requirements.txt
                echo "$NEW_HASH" > "$REQUIREMENTS_HASH"
              fi
              echo "Virtual environment setup complete!"
            else
              source "$VENV/bin/activate"

              # Check if requirements have changed
              if [ -f "requirements.txt" ]; then
                if [ ! -f "$REQUIREMENTS_HASH" ] || [ "$NEW_HASH" != "$(cat $REQUIREMENTS_HASH)" ]; then
                  echo "Requirements have changed. Updating..."
                  pip install --upgrade pip
                  pip install -r requirements.txt
                  echo "$NEW_HASH" > "$REQUIREMENTS_HASH"
                fi
              fi
            fi

            # Print Python version
            echo "Using Python: $(python --version)"
          '';
        };
      });
}

Using the Environment

Once you have the flake.nix file in your project's root directory (assuming Nix with flakes is installed), the only command you need to run is nix develop. Running this command will drop you into an isolated development shell.

Within this shell, you'll have access to the tools defined in the flake, such as the specific Python version requested. Additionally, the custom shellHook I included in the flake automates the management of your Python dependencies. This hook automatically creates and activates a standard Python virtual environment (.venv). More importantly, it checks your requirements.txt file and automatically installs or updates your Python packages using pip whenever the contents of requirements.txt change. And everything isolated for this specific repo without any leakeges to the outside world!

The result is a fully prepared, self-contained development environment that keeps your project dependencies neatly isolated from the rest of your system, and also isolates the core tools like the Python interpreter itself – a key advantage over managing global installations or relying solely on .venv.

Why not docker?

Now, why not Docker? While Docker is awesome for deploying things, for active development where you're constantly tweaking code, it can feel a bit heavyweight. Jumping in and out of container builds or dealing with bind mounts just isn't as immediate as simply entering an interactive shell. That's it.

Bonus: Comparing Perplexity vs. local tool reports

So, I put a short summary request for "LLM history, roots, most impactful studies (scan all starting with 20th century)" to both Perplexity and the local tool we've been discussing. My goal was to show that for basic deep research, you don't necessarily need to pay for a service; you can configure your own using free tiers like Gemini for LLM tasks and a free search API like Serper, which the local tool utilises to scrape the web.

To get an unbiased comparison of the results, I asked a third LLM to analyze the style and substance of the two reports. Here's a summary of its findings:

While Article 2 (Perplexity) is more concise and its table of "Most Impactful Studies" is a valuable quick reference, Article 1 (Local tool) provides a richer, more detailed, and better-structured historical account that allows for a deeper understanding of the evolution of LLMs.

And you know what?:

You can always tweak the local tool implementation per your own needs! (e.g. I've adjusted it specifically for my needs to narrow down the set of resources I want it to look into). I mean, it's programming, you do whatever you want! And using nix preparing your dev setup as simple as running just 1 command, nix develop!

Ruby on Rails: Your Service Layer is a Lie

Alexander Shagov — Wed, 15 Jan 2025 10:00:57 +0000

If you're a Rails developer, you've probably seen (or written) code that looks like this:

class UserService
  def self.create(params)
    user = User.new(params)
    if user.save
      UserMailer.welcome_email(user).deliver_later
      user
    else
      false
    end
  end
end

# In your controller
def create
  @user = UserService.create(user_params)
  if @user
    redirect_to @user, notice: 'User was successfully created.'
  else
    render :new
  end
end

Look familiar? We've all been there. We've all written these service objects because "that's what good Rails developers do." But let me ask you something: What value did that service layer actually add?

We've been told that service layers:

Separate business logic from models
Make code more testable
Keep controllers thin
Follow single responsibility principle

When Your Service is Just Extra Typing

Many Rails codebases are littered with service objects that do nothing but proxy method calls to ActiveRecord models. Let's look at a real-world example:

class CommentService
  def self.create_for_post(post, user, content)
    Comment.create(
      post: post,
      user: user,
      content: content
    )
  end
end

What did we gain here? Nothing except an extra file to maintain and an additional layer to jump through while debugging. The service is literally just passing through parameters to Comment.create. Even worse, we've actually lost functionality compared to working with the model directly - we no longer have access to ActiveRecord's rich API for handling validation errors and callbacks.

When You Actually Need a Service Layer

Let's be clear: Service objects aren't always bad. (In fact I've written a separate article on rethinking service objects: https://dev.to/alexander_shagov/ruby-on-rails-rethinking-service-objects-4l0b)

1. Orchestrating Complex Operations

module Orders
  class ProcessingWorkflow
    include Dry::Transaction

    step :start_processing
    step :process_payment
    step :allocate_inventory
    step :create_shipping_label
    step :send_confirmation
    step :complete_processing

    private

    def start_processing(input)
      order = input[:order]
      order.update!(status: 'processing')
      Success(input)
    rescue => e
      Failure([:processing_failed, e.message])
    end

    def process_payment(input)
      order = input[:order]
      payment = Payments::Gateway.new.charge(
        amount: order.total,
        token: order.payment_token
      )
      Success(input.merge(payment: payment))
    rescue => e
      Failure([:payment_failed, e.message])
    end

    def allocate_inventory(input)
        # ...
    end

    def create_shipping_label(input)
        # ...
    end

    def send_confirmation(input)
      OrderMailer.confirmation(input[:order]).deliver_later
      Success(input)
    rescue => e
      Failure([:notification_failed, e.message])
    end

    def complete_processing(input)
      order = input[:order]
      order.update!(status: 'processed')
      Success(input)
    rescue => e
      Failure([:completion_failed, e.message])
    end
  end
end

2. Handling External Services

module Subscriptions
  class StripeWorkflow
    include Dry::Transaction

    step :validate_subscription
    step :create_stripe_customer
    step :create_stripe_subscription
    step :update_user_records

    private

    def validate_subscription(input)
      contract = Subscriptions::ValidationContract.new
      result = contract.call(input)
      result.success? ? Success(input) : Failure([:validation_failed, result.errors])
    end

    def create_stripe_customer(input)
        # ... stripe code
    end

    def create_stripe_subscription(input)
        # ... stripe code
    end

    def update_user_records(input)
      user = input[:user]
      user.update!(
        stripe_customer_id: input[:customer].id,
        stripe_subscription_id: input[:subscription].id,
        subscription_status: input[:subscription].status
      )
      Success(input)
    rescue => e
      Failure([:record_update_failed, e.message])
    end
  end
end

3. Complex Business Rules

module Loans
  class ApplicationProcess
    include Dry::Transaction

    step :validate_application
    step :check_credit_score
    step :evaluate_debt_ratio
    step :calculate_risk_score
    step :determine_approval
    step :process_result

    private

    def validate_application(input)
      contract = Loans::ApplicationContract.new
      result = contract.call(input)
      result.success? ? Success(input) : Failure([:validation_failed, result.errors])
    end

    def check_credit_score(input)
      application = input[:application]
      if application.credit_score < 600
        Failure([:credit_score_too_low, "Credit score below minimum requirement"])
      else
        Success(input)
      end
    end

    def evaluate_debt_ratio(input)
      calculator = Loans::DebtRatioCalculator.new(input[:application])
      ratio = calculator.compute

      if ratio > 0.43
        Failure([:debt_ratio_too_high, "Debt-to-income ratio exceeds maximum"])
      else
        Success(input.merge(debt_ratio: ratio))
      end
    end

    def calculate_risk_score(input)
        # ...
    end

    def determine_approval(input)
        # ...
    end

    def process_result(input)
      application = input[:application]

      if input[:approved]
        rate_calculator = Loans::InterestRateCalculator.new(
          application: application,
          risk_score: input[:risk_score]
        )

        application.update!(
          status: 'approved',
          interest_rate: rate_calculator.compute,
          approval_date: Time.current
        )
        LoanMailer.approval_notice(application).deliver_later
      else
        application.update!(status: 'rejected')
        LoanMailer.rejection_notice(application).deliver_later
      end

      Success(input)
    rescue => e
      Failure([:processing_failed, e.message])
    end
  end
end

The examples above represent what I consider valid uses of a service layer - or more accurately, business processes. They demonstrate clear cases where abstraction adds real value: complex workflows, external service integration, and domain-rich business rules and etc.
But the key takeaway isn't just about when to use these patterns - it's about questioning our default approaches to architecture. Too often, we reach for service objects because "that's how it's done" or because we've read that "fat models are bad." Instead, we should:

Start simple - directly in models and controllers
Let complexity guide abstraction - not the other way around
Think in terms of processes and workflows rather than generic "services"
Question established patterns - just because everyone's doing it doesn't make it right for your specific case

! More importantly, if you're part of a large team, establish and agree on a unified approach first. Having half your codebase using traditional service objects and the other half using process-oriented workflows will likely create more problems than it solves. Architectural decisions should be team decisions, backed by clear conventions and documentation.
Remember: Every layer of abstraction is a trade-off. Make sure you're getting enough value to justify the complexity cost.

Why Use Nix package manager, Even on macOS?

Alexander Shagov — Mon, 23 Sep 2024 07:55:20 +0000

Some time ago I wrote a short article on nix first steps (https://dev.to/alexander_shagov/nix-first-steps-4066). However, I realized that I need one more to quickly explain why generally prefer nix over non-nix setups. So here it is.

As a macOS user, you might wonder why you should consider using Nix (package manager) when you already have package managers like Homebrew.

⭐️ One of the most significant advantages of Nix is its ability to create reproducible environments. This means you can:

Easily share your exact development setup with teammates.
Recreate your entire system setup on a new machine with minimal effort.

⭐️ With Nix (especially when using Home Manager), you define your entire system configuration in code. This approach offers several benefits:

Your system setup becomes version-controlled.
You can review and roll back changes easily.
No more conflicts between different versions of the same library.
Easy testing of different software versions without affecting your system.

⭐️ Nix, especially with flakes, allows you to define project-specific environments:

Each project can have its own set of tools and dependencies.
No need to globally install project-specific tools, reducing system clutter.
If a local dependency update breaks something, you can easily roll back to a previous state (e.g. roll back node.js to the previous version in 1 click).

As a macOS user, I initially hesitated to adopt Nix, comfortable with my Homebrew + Ruby version manager + Node version manager + Docker setup.
However, after experiencing the reproducibility and declarative nature of Nix, I've found it invaluable. It's particularly useful for managing multiple development environments and ensuring consistency across my personal and work machines.

While the learning curve can be steep, the long-term benefits in terms of system management and development workflow have been worth the initial investment.

Diving into the Nix world might be overwhelming at first. Check out the 'First Steps' article (https://dev.to/alexander_shagov/nix-first-steps-4066), which helps define the important vocabulary.

Balancing Authenticity and Self-Promotion in the Tech Industry

Alexander Shagov — Mon, 23 Sep 2024 07:40:40 +0000

Picture this: You're a software developer at MegaCorp, writing code day in and day out. Your contributions, while necessary, often feel like drops in a vast ocean. Then comes the time to update your resume or LinkedIn profile. Suddenly, you're faced with a choice: do you stick to the unpolished truth, or do you make it sound big?

Welcome to the modern developer's dilemma.

In today's hyper-competitive GPT-powered tech industry, the pressure to stand out is immense. We're told to "build our personal brand," "showcase our achievements," and "sell ourselves" to potential employers. But what happens when the reality of our day-to-day work doesn't quite match up to these expectations?

Let's be honest - not every developer is working on revolutionary AI algorithms or building the next unicorn startup. Many of us are maintaining legacy systems, squashing bugs, or implementing small features that, while important, hardly set the world on fire. Yet, scroll through LinkedIn, and you'd think every developer was single-handedly revolutionizing their industry.

This gap between reality and marketing creates tension. On one side, there's the pull towards honesty and being real. On the other, there's the practical need to compete in a job market that seems to reward those who can write the most impressive-sounding bullet points.
And... it often works. HR teams and recruiters, often not knowing the technical details of our work, can be swayed by well-written stories of impact and achievement. A basic task reframed as a "critical initiative" might just be the difference between getting an interview or being lost in the resume pile.

And the situation is getting worse with GPT-powered systems checking GPT-generated CVs..

But at what cost?

Original: "Maintained backend systems."
Polished: "Architected and implemented mission-critical backend infrastructure, resulting in 99.99% uptime and 30% improvement in system efficiency."

Comment below with your experiences navigating authenticity in the tech industry. How do you balance self-promotion with genuine representation of your work?

The "IO to the Boundary" principle

Alexander Shagov — Tue, 10 Sep 2024 14:59:13 +0000

In software architecture, many principles and patterns have emerged over time. However, a lot of these can be boiled down to a single idea: the "IO to the Boundary" principle. This principle suggests that all input/output operations, like database queries, API calls, or file system interactions, should be pushed to the edges (or boundaries) of your application.

Let's look at what some other ideas tell us:

Functional Core, Imperative Shell: This principle suggests keeping the core of your application pure and functional, while handling side effects (IO) in an outer layer. This is basically another way of saying "IO to the Boundary."
Clean Architecture: Proposed by Robert C. Martin, this architecture emphasizes separating concerns and having dependencies point inwards, which fits with keeping IO at the edges.
Command Query Responsibility Segregation (CQRS): While not mainly about IO boundaries, CQRS often leads to separating read and write operations. This separation can support the "IO to the Boundary" principle by making it easier to isolate and manage IO operations at the system's edges.

Example

The Client Code interacts with both WeatherAPI (to create an object instance) and WeatherReport (to generate a report).
WeatherReport uses WeatherAPI internally to fetch temperature data.
WeatherAPI encapsulates the IO operations, making the actual HTTP request to the External Weather API.

This structure keeps the core application logic (WeatherReport) free from direct IO concerns, pushing those responsibilities to the edges (WeatherAPI and beyond).

Client Code       WeatherReport       WeatherAPI         External Weather API
     |                   |                   |                  |
     |                   |                   |                  |
     |  new WeatherAPI()                     |                  |
     |--------------------------------------->                  |
     |                   |                   |                  |
     |  new WeatherReport(weather_api)       |                  |
     |------------------>|                   |                  |
     |                   |                   |                  |
     |  generate_report('New York')          |                  |
     |------------------>|                   |                  |
     |                   |                   |                  |
     |                   | get_temperature('New York')          |
     |                   |------------------>|                  |
     |                   |                   |                  |
     |                   |                   | HTTP GET request |
     |                   |                   |----------------->|
     |                   |                   |                  |
     |                   |                   | JSON response    |
     |                   |                   |<-----------------|
     |                   |                   |                  |
     |                   |     temperature   |                  |
     |                   |<------------------|                  |
     |                   |                   |                  |
     |  formatted report |                   |                  |
     |<------------------|                   |                  |
     |                   |                   |                  |

    [Application Boundary]              [IO Boundary]

Note on oversimplification

From my perspective, the key to effective architecture is finding the right balance between simplification and necessary complexity (sounds vague but that's true..). It's becoming clear that most mid-sized projects don't need the level of complexity they often include. But some do. While I recognize that the real world is more complex, with evolving projects, changing teams, and loss of knowledge when an organization changes, it's crucial to remember that sometimes the best abstraction is no abstraction at all.

Code samples

Let's consider "good" and "bad" examples (I'll be using Ruby and Ruby on Rails to convey the ideas)

Bad example

# app/controllers/weather_controller.rb
class WeatherController < ApplicationController
  def report
    city = params[:city]
    api_key = ENV['WEATHER_API_KEY']

    response = HTTP.get("https://api.weather.com/v1/temperature?city=#{city}&key=#{api_key}")
    data = JSON.parse(response.body)

    temperature = data['temperature']
    feels_like = data['feels_like']

    report = "Weather Report for #{city}:\n"
    report += "Temperature: #{temperature}°C\n"
    report += "Feels like: #{feels_like}°C\n"

    if temperature > 30
      report += "It's hot outside! Stay hydrated."
    elsif temperature < 10
      report += "It's cold! Bundle up."
    else
      report += "The weather is mild. Enjoy your day!"
    end

    render plain: report
  end
end

It's evident that the code smells:

Mixing IO operations (API call) with business logic in the controller.
Directly parsing and manipulating data in the controller.
Generating the report text within the controller action.

Good example

# app/controllers/weather_controller.rb
class WeatherController < ApplicationController
  def report
    result = WeatherReport::Generate.new.call(city: params[:city])

    if result.success?
      render plain: result.value!
    else
      render plain: "Error: #{result.failure}", status: :unprocessable_entity
    end
  end
end

# app/business_processess/weather_report/generate.rb
require 'dry/transaction'

module WeatherReport
  class Generate
    include Dry::Transaction

    step :validate_input
    step :fetch_weather_data
    step :generate_report

    private

    def validate_input(city:)
      schema = Dry::Schema.Params do
        required(:city).filled(:string)
      end

      result = schema.call(city: city)
      result.success? ? Success(city: result[:city]) : Failure(result.errors.to_h)
    end

    def fetch_weather_data(city:)
      result = WeatherGateway.new.fetch(city)
      result.success? ? Success(city: city, weather: result.value!) : Failure(result.failure)
    end

    def generate_report(city:, weather:)
      report = WeatherReport.new(city, weather).compose
      Success(report)
    end
  end
end

# app/business_processess/weather_report/weather_gateway.rb
class WeatherGateway
  include Dry::Monads[:result]

  def fetch(city)
    response = HTTP.get("https://api.weather.com/v1/temperature?city=#{city}&key=#{ENV['WEATHER_API_KEY']}")
    data = JSON.parse(response.body)

    Success(temperature: data['temperature'], feels_like: data['feels_like'])
  rescue StandardError => e
    Failure("Failed to fetch weather data: #{e.message}")
  end
end

# app/business_processess/weather_report/weather_report.rb
class WeatherReport
  def initialize(city, weather)
    @city = city
    @weather = weather
  end

  def compose
    # ...
  end
end

What has changed:

Separating concerns: The controller only handles HTTP-related tasks.
Using dry-transaction to create a clear flow of operations, with each step having a single responsibility.
Pushing IO operations (API calls) to the boundary in the WeatherAPI service.

Note on complexity

We should be realistic though, if we're talking about a simple 1-pager app generating the weather reports, well, who cares? It just works and we definitely do not want to introduce any additional layers.
However, if we care about the future extendability, thinking about these kind of things is crucial.

Final note

Many of the architectural principles and patterns we encounter today are not entirely new concepts, but rather evolved or repackaged ideas from the past. I hope that you see now that the "IO to the Boundary" principle is one such idea that has been expressed in various forms over the years.

Comments / suggestions appreciated! 🙏

Ruby on Rails: Rethinking Service Objects

Alexander Shagov — Wed, 04 Sep 2024 13:03:36 +0000

In the Ruby on Rails community, service objects have gained popularity as a way to encapsulate business logic and keep controllers and models lean. However, there's a growing trend of misusing service objects, particularly those with "-er" or "-or" suffixes. This article aims to shed light on poorly implemented service objects and provide guidance on creating more effective, domain-focused alternatives.

Many developers tend to name their service objects with suffixes like -er or -or, such as ArticleCreator or UserAuthenticator. While this naming convention may seem intuitive, it often leads to a procedural style of programming rather than embracing the object-oriented nature of Ruby.

It's becoming evident that service objects the way we often see them are not actually "objects", but just a procedures.. or better to say, processess.

Let's take a look at the real-world example of a codebase powering the dev.to community: https://github.com/forem/forem/blob/main/app/services/articles/creator.rb.
The class seems okay at first glance; at least the code is organized and lives in its own space. It could be workable. However, we're just hiding the problem in the long term.

# The code structure is taken from https://github.com/forem/forem/blob/main/app/services/articles/creator.rb

class ArticleCreator
  def initialize(user, article_params)
    @user = user
    @article_params = article_params
  end

  def call
    rate_limit!
    create_article
    subscribe_author
    refresh_auto_audience_segments if @article.published?
    @article
  end

  private

  def rate_limit!
    # Rate limiting logic
  end

  def create_article
    @article = Article.create(@article_params.merge(user_id: @user.id))
  end

  def subscribe_author
    NotificationSubscription.create(user: @user, notifiable: @article, config: "all_comments")
  end

  def refresh_auto_audience_segments
    @user.refresh_auto_audience_segments
  end
end

A Domain-Centric Approach

Instead of focusing solely on actions (creating, updating, deleting), we should model our service objects around domain concepts and processes. Hence my suggestion: let's stop pretending service objects are objects and start calling them processess instead.
NOTE: I'm not talking about DDD (Domain-Driven design) since it's a whole separate topic, however, we can be inspired by some of the concepts.

I'll be using dry-* libraries to demonstrate how a process might have looked like:

module Articles
  class PublishingProcess
    include Dry::Transaction

    step :validate
    step :rate_limit
    step :create_article
    step :subscribe_author
    step :refresh_auto_audience_segments
    step :notify_subscribers

    private

    def validate(input)
      contract = Articles::ValidationContract.new
      result = contract.call(input)
      result.success? ? Success(input) : Failure(result.errors)
    end

    def rate_limit(input)
      limiter = Articles::PublishingQuota.new(input[:user])
      limiter.within_limit? ? Success(input) : Failure(:rate_limited)
    end

    def create_article(input)
      repository = Articles::Repository.new
      article = repository.create(input[:user], input[:params])
      Success(input.merge(article: article))
    end

    def subscribe_author(input)
      subscription = Articles::AuthorSubscription.new(input[:user], input[:article])
      subscription.create
      Success(input)
    end

    def refresh_auto_audience_segments(input)
      # NOTE: the naming might not be the best one for this case since I'm not aware about the actual business logic behind
      audience = Articles::Audience.new(input[:user])
      audience.refresh_segments
      Success(input)
    end

    def notify_subscribers(input)
      publication = Articles::SubscriberNotification.new(input[:article])
      publication.dispatch
      Success(input)
    end
  end
end

See, not only the business process is very well defined, but it also deals with domain-centric objects: Articles::ValidationContract, Articles::PublishingQuota, Articles::Repository, Articles::AuthorSubscription and etc.

⭐ Thanks to having a clear separation between Processes and Domain objects we'll stop pretending that we play in OOP game when dealing with service objects.

Let's imagine an ideal world where each app consisted of Process-like implementations. As a result, our app might look like a set of business processes. One process might start another as an async job, or some processes might be executed in the background on scheduled basis. Yet, it doesn't change the fact that an app consists of a set of business processes.

# Hotel Booking Process
module Bookings
  class HotelReservationProcess
    include Dry::Transaction

    step :check_room_availability
    step :calculate_total_cost
    step :process_deposit
    step :create_reservation
    step :send_confirmation
    step :schedule_reminders
  end
end

# User Registration Process
module Users
  class RegistrationProcess
    include Dry::Transaction

    step :validate_user_data
    step :check_unique_email
    step :create_user
    step :send_verification_email
    step :assign_default_roles
  end
end

I think it goes without saying that having a clear separation of processes and a set of domain-centric objects powering these processes is a cleaner way to write business logic. However, I understand that the "ideal" world and the "real" world are sometimes completely different pictures. It always boils down to engineering contracts established in a particular team or the whole organization, and sometimes it's not that easy to change habits, especially when we're talking about legacy production applications.

Nevertheless, what we can do is refine our mental models to try to perceive "business processes" instead of "some" objects, and incorporate the business language into the domain language of our system.

Nix first steps

Alexander Shagov — Wed, 04 Sep 2024 08:33:10 +0000

It might be overwhelming to dive into the Nix world, but this little glossary should help refine your understanding of the tools you might encounter when starting your journey.

UPD: I wrote one more short article to articulate why I prefer nix over non-nix setups in general: https://dev.to/alexander_shagov/why-use-nix-even-on-macos-786

Nix Package Manager – The core tool that allows declarative and reproducible package management.

NixOS – A Linux distribution built entirely on the Nix package manager. It's better to start with nix package manager alone before switching to NixOS completely.

Home Manager – Manages user packages, dotfiles, environment variables, shell configurations, and more. Allows for portable user environments across different machines.

Flakes – Provides a standardized structure for Nix projects, improving reproducibility and composability. It's worth noting that while Flakes are still technically experimental, they have been widely adopted by the Nix community due to their benefits. Many newer Nix configurations and projects are built using Flakes.

Old flow vs New flow

When you start searching for actual commands, you might encounter that some of them have different syntax (e.g., 'nix build' vs 'nix-build').

https://nixos-and-flakes.thiscute.world/nixos-with-flakes/introduction-to-flakes

Based on the article, there are two "flows" or approaches to using Nix: the old (or classic) flow and the new flow using flakes.

New Flow (Flakes and New CLI):

Introduces flake.nix and flake.lock files.
Uses new CLI commands that start with "nix" (e.g., nix develop, nix shell, nix build).
Replaces channels with explicit inputs in flake.nix.
Aims for improved reproducibility and composability.

Old Flow (Classic Nix):

Used commands like nix-channel, nix-env, nix-shell, and nix-build.
Relied on channels for package management.
Less standardized structure for Nix projects.
Could lead to less reproducible builds in some cases.

The new flow is essentially an evolution of Nix, addressing some limitations of the classic approach and borrowing ideas from other modern package managers (like npm, Cargo, etc.).

Assuming you're not using NixOS itself but, let's say, macOS, your flow of working with your development environment might look like this:

1) Use home-manager (preferably with flakes) to manage user-specific packages, tools, and configurations. This includes system-wide tools like Emacs, as well as dotfiles and environment settings.

2) For each project you're working on, create a flake.nix file to define the project-specific development environment and dependencies.

The aim of the article was to provide a good starting point and set up the mental model for further readings. Even though I didn't set a goal to share specific code snippets, here's the example of a home-manager (home.nix) file defining the global configuration on my MacOS. This configuration defines the global state of my system. Any project-related pieces live a in separate flake.nix files in their own namespaces. NOTE: I'm not using brew anyhow!


{ config, pkgs, ... }:

{
  home.username = "<username>";
  home.homeDirectory = "<homeDirectory>";

  home.stateVersion = "24.05";

  home.packages = with pkgs; [
    direnv
    ripgrep
    htop
    inetutils
    jq
    emacs29
    emacsPackages.vterm
  ];

  home.shellAliases = {
    # ============ git aliases =====================
    gs = "git status";
    gcm = "git checkout main && git pull";
    gc = "git checkout";
  };

  home.sessionVariables = {
    EDITOR = "emacs";
  };

  # ======== Zsh configuration ============

  programs.zsh = {
    enable = true; # Enable managing the Zsh configuration

    initExtra = ''

      # Private ENV vars configuration
      if [ -f ~/.bashrc_private ]; then
        . ~/.bashrc_private
      fi    

      # ========= Prompt with a branch ========
      function git_branch_name() {
           git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '='
      }
      autoload -Uz colors && colors
      setopt prompt_subst
      prompt='%F{yellow}%~/%f [%F{green}$(git_branch_name)%f] > '

    '';
  };

  programs.direnv = {
    enable = true;
    # enableBashIntegration = true; # see note on other shells below
    nix-direnv.enable = true;
  };

  # Let Home Manager install and manage itself.
  programs.home-manager.enable = true;
}

Any time I need to add/remove system-wide package, or adjust, let's say, zsh configuration, it just boils down to editing the home.nix file and running the home-manager switch to apply the change (or home-manager build to see if a build compiles correctly).

Where to look for packages

Given you want to install htop. Just use the search.nixos.org and put the package name into your home.nix file. Run home-manager switch and you'll have your htop configured automatically (e.g. /Users/<username>/.nix-profile/bin/htop)

How to install a specific version of a package?

If you want to install a specific version of a package (not the latest one by default), you can search at nixhub.io. There, you'll see a specific Nixpkgs Reference you should use in your home.nix file to point to a specific version you're interested in.

Useful links for further reading

Introduction to Flakes: https://nixos-and-flakes.thiscute.world/nixos-with-flakes/introduction-to-flakes
Nix flakes syntax basics: https://serokell.io/blog/practical-nix-flakes
Official nix package manager step-by-step guide: https://nixos.org/guides/nix-pills/01-why-you-should-give-it-a-try
A good article where a person shows how they cleaned up their $HOME with nix: https://juliu.is/tidying-your-home-with-nix/

⭐ Comments and more useful articles for nix beginners appreciated!