Thronglets

• Why Use Thronglets?
• Use Cases
• Overview
• Key Features
• Installation
• Directory Structure
• Core Components
  • Workflows
  • Activities
  • Command Line Interface
• Input/Output Validation
• Development Mode
• Error Handling
• Best Practices
• Support
• License
• Code of conduct
• Contribution guide

Decoupling a monolith is complex and risky without the right tools. Thronglets gives you insight into your codebase, helps you plan a phased decomposition strategy, and reduces the cognitive and operational overhead of large-scale refactoring efforts.

• Legacy systems modernization
• Microservice migration strategies
• Technical debt management
• Domain-driven design alignment

Thronglets is an open-source Ruby toolkit designed to help engineering teams modernize and decompose monolithic applications into modular, scalable services. Built on top of Temporal, it provides a structured approach to breaking down legacy Ruby applications, with a particular focus on Ruby on Rails monoliths.

1. Workflow Management

   • Built-in workflow orchestration using Temporal
   • Support for long-running processes
   • Automatic workflow registration and management

2. Activity Management

   • Structured activity definitions
   • Input/Output validation
   • Automatic activity registration

3. Code Organization

   • Conventional directory structure
   • Automatic code loading with Zeitwerk
   • Hot-reloading capabilities

gem 'thronglets'

Or install via command line:

gem install thronglets

Requirements:

• Ruby >= 3.2
• Temporal server running

Thronglets expects the following directory structure:

app/
├── activities/     # Activity definitions
├── actors/        # Actor classes
├── workflows/     # Workflow definitions
├── models/        # Domain models
└── models/concerns/  # Shared concerns

Workflows are the core orchestration units in Thronglets. They inherit from Thronglets::Workflow:

class MyWorkflow < Thronglets::Workflow
  input do
    # Define input schema using dry-schema
  end

  output do
    # Define output schema using dry-schema
  end

  def call
    # Implement workflow logic
  end
end

Activities are the individual units of work, inheriting from Thronglets::Activity:

class MyActivity < Thronglets::Activity
  input do
    # Define input schema
  end

  output do
    # Define output schema
  end

  def call
    # Implement activity logic
  end
end

Thronglets provides a CLI with several commands:

# Display version
thronglets -v

# Start worker
thronglets -w

# Start in listen mode (auto-reload)
thronglets -l

# Start console
thronglets -c

Thronglets uses dry-schema for input/output validation:

class MyWorkflow < Thronglets::Workflow
  input do
    required(:name).filled(:string)
    required(:age).filled(:integer)
  end

  output do
    required(:success).filled(:bool)
    required(:data).hash
  end
end

For development:

1. Start in listen mode: thronglets -l
2. Make code changes
3. Automatic reload happens on file changes
4. Use console mode for exploration: thronglets -c

Thronglets provides structured error handling:

• InputValidationError for invalid inputs
• OutputValidationError for invalid outputs
• Automatic error formatting to JSON
• Standardized error responses

1. Code Organization

   • Keep activities atomic and focused
   • Use workflows for orchestration
   • Leverage input/output schemas

2. Development Workflow

   • Use listen mode during development
   • Implement proper input/output validation
   • Follow the directory structure conventions

3. Error Handling

   • Always validate inputs and outputs
   • Use proper error classes
   • Implement proper error recovery in workflows

• GitHub Issues: https://github.com/kkdoo/thronglets/issues
• License: MIT
• Author: Artem Mashchenko

If you want to report a bug, or have ideas, feedback or questions about the gem, let me know via GitHub issues and I will do my best to provide a helpful answer. Happy hacking!

The gem is available as open source under the terms of the MIT License.

Everyone interacting in this project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Pull requests are welcome!