Overview

Relevant source files

Purpose and Scope

This document provides a high-level overview of the Solid::Process library, its architecture, and core components. It explains what Solid::Process is, how it works, and how the major subsystems interact. For detailed information on specific features:

For fundamental concepts and philosophy, see Core Concepts
For step-by-step learning, see the Reference Guide
For testing strategies, see Testing Patterns and Best Practices
For development setup and multi-version testing, see Development Setup

What is Solid::Process?

Solid::Process is a Ruby/Rails library for encapsulating business logic into composable, testable processes. It provides a structured approach to writing business operations with:

Explicit inputs with type validation via Solid::Input
Explicit outputs as Solid::Success or Solid::Failure results
Process composition through dependency injection and the Steps DSL
Built-in observability via event logging and instrumentation

The library is designed for progressive mastery: start with simple input/output processes and add sophistication (steps, dependencies, callbacks) as complexity demands.

Sources: README.md42-69 docs/overview/010_KEY_CONCEPTS.md9-25

Core Architecture

The following diagram shows the main architectural components and their relationships using actual class and module names from the codebase:

Sources: Diagram synthesis from README.md1-227 High-Level Architecture Diagrams (provided context)

Core Components

Component	Class/Module	Purpose	Defined In
Process Base	`Solid::Process`	Base class for all business logic processes	lib/solid/process.rb
Input Validation	`Solid::Input`	ActiveModel-based input objects with validation	lib/solid/input.rb
Result Types	`Solid::Success`, `Solid::Failure`	Explicit success/failure outcomes	Provided by `solid-result` gem
Data Modeling	`Solid::Model`	ActiveModel features for data objects	lib/solid/model.rb
Value Objects	`Solid::Value`	Immutable single-value objects	lib/solid/value.rb
Process Execution	`Solid::Process::Caller`	Manages process lifecycle and validation	lib/solid/process/caller.rb
DSL Definition	`Solid::Process::ClassMethods`	Provides `input`, `deps`, steps DSL	lib/solid/process/class_methods.rb
Configuration	`Solid::Process::Config`	Global configuration singleton	lib/solid/process/config.rb
Event Logging	`Solid::Process::EventLogs`	Process execution instrumentation	lib/solid/process/event_logs.rb

Sources: lib/solid/process.rb lib/solid/input.rb lib/solid/model.rb lib/solid/value.rb

Basic Process Structure

Every process inherits from Solid::Process and defines two required components:

Example from codebase:

examples/business_processes/user_creation.rb1-20 demonstrates this structure:

input do ... end block defines attributes and validations
def call(attributes) contains the business logic
Returns Success(:user_created, ...) or Failure(:user_not_created, ...)

Sources: README.md112-139 docs/REFERENCE.md82-155

Process Execution Flow

The following diagram shows how a process executes from invocation through validation to result, using actual method names and module interactions:

Key execution points:

Caller interception - The Solid::Process::Caller module is prepended to intercept call lib/solid/process/caller.rb
Input instantiation - Creates an Input object from raw data lib/solid/process/caller.rb25-35
Validation gate - If input.invalid?, returns Failure(:invalid_input) without executing business logic lib/solid/process/caller.rb37-43
Call execution - If valid, invokes the call method with validated attributes hash lib/solid/process/caller.rb45-50
Result return - Process must return Success(:type, **data) or Failure(:type, **data)

Sources: lib/solid/process/caller.rb Process Execution Flow diagram (provided context)

Dependency Structure

The library depends on two main external dependencies:

Dependency	Version	Purpose
`solid-result`	`~> 2.0`	Provides `Success`/`Failure` result types and event logging infrastructure
`activemodel`	`>= 6.0`	Powers `Solid::Model` with attributes, validations, and callbacks

Sources: solid-process.gemspec42-43

Ruby and Rails Version Support

Solid::Process is tested across a wide compatibility matrix:

Ruby Version	Rails 6.0	Rails 6.1	Rails 7.0	Rails 7.1	Rails 7.2	Rails 8.0	Rails 8.1	Rails Edge
2.7	✅	✅	✅	✅	-	-	-	-
3.0	✅	✅	✅	✅	-	-	-	-
3.1	-	-	✅	✅	✅	-	-	-
3.2	-	-	✅	✅	✅	✅	-	-
3.3	-	-	✅	✅	✅	✅	✅	✅
3.4	-	-	-	-	✅	✅	✅	✅
4.x	-	-	-	-	-	-	✅	✅

This matrix is enforced through the Appraisals-based testing infrastructure. See Multi-Version Testing Strategy for implementation details.

Sources: README.md26-38 Appraisals

Repository Structure

Key directories:

lib/solid/ - Core library code
lib/solid/process/ - Process execution machinery
lib/solid/validators/ - Custom ActiveModel validators
test/solid/ - Comprehensive test suite
docs/ - Documentation including the Reference Guide
examples/ - Real-world example processes
gemfiles/ - Generated Appraisal gemfiles for multi-version testing

Sources: Repository file structure

Key Concepts and Philosophy

Solid::Process embraces emergent design - starting simple and adding sophistication based on actual needs rather than upfront speculation. The development mantra is:

Make it Work - Basic input + call + Success/Failure
Make it Better - Add Steps DSL, validations, normalization
Make it Even Better - Add dependencies, composition, callbacks when complexity demands

This approach reduces over-engineering while providing a clear path for scaling complexity.

For detailed philosophical discussion and design patterns, see Design Patterns and Philosophy.

Sources: docs/overview/010_KEY_CONCEPTS.md31-42 docs/REFERENCE.md43-53

Integration with Rails

While Solid::Process works in pure Ruby applications, it provides specific Rails integrations:

Feature	Description	Module/Method
ActiveRecord Transactions	`rollback_on_failure { }` wraps steps in a transaction	lib/solid/process.rb
Custom Validators	ActiveModel validators: `email`, `uuid`, `id`, `kind_of`, etc.	lib/solid/validators/
ActiveModel Features	Full validation, dirty tracking, callbacks via `Solid::Model`	lib/solid/model.rb
Logger Integration	`BasicLoggerListener` uses `Rails.logger` by default	lib/solid/process/event_logs/basic_logger_listener.rb

For detailed Rails integration patterns, see Rails Integration.

Sources: docs/overview/080_RAILS_INTEGRATION.md lib/solid/validators/

Observable Process Execution

One of Solid::Process's key features is comprehensive observability without code pollution. The EventLogs system captures every step of execution:

Example log output structure:

#0 Account::OwnerCreation
 * Given(uuid:, owner:)
   #1 User::Creation
    * Given(name:, email:, password:)
    * Continue() from method: validate_email
    * Continue(user:) from method: create_user
    * Success(:user_created, user:)
 * Continue(user:) from method: create_owner
 * Success(:account_owner_created, user:, account:)

For configuration and usage details, see Event Logging System.

Sources: lib/solid/process/event_logs.rb docs/REFERENCE.md1307-1401

Testing Infrastructure

The repository maintains 100% test coverage across multiple Ruby and Rails versions using a sophisticated testing matrix:

For detailed testing strategy documentation, see Multi-Version Testing Strategy.

Sources: Appraisals .github/workflows/main.yml bin/matrix

Getting Started

To begin using Solid::Process:

Installation: bundle add solid-process (see README.md95-108)
First Process: Create a class with input and call (see Your First Process)
Learn the Basics: Input validation, Success/Failure results (see Basic Usage and Results and Outcomes)
Progressive Enhancement: Add Steps DSL, dependencies, callbacks as needed (see Steps DSL and Composition, Dependencies and Injection)
Testing: Use dependency injection for isolation (see Testing Patterns and Best Practices)

Sources: README.md80-145 docs/REFERENCE.md1-79

Documentation Resources

Resource	Purpose	Location
README	Quick start, installation, basic examples	README.md
Reference Guide	Complete feature documentation with examples	docs/REFERENCE.md
Overview Docs	Bite-sized topic guides	docs/overview/
Examples	Working code examples	examples/
Solid Rails App	Complete Rails application example	External repository

Sources: README.md147-169

Overview

Relevant source files

Purpose and Scope

For fundamental concepts and philosophy, see Core Concepts
For step-by-step learning, see the Reference Guide
For testing strategies, see Testing Patterns and Best Practices
For development setup and multi-version testing, see Development Setup

What is Solid::Process?

Solid::Process is a Ruby/Rails library for encapsulating business logic into composable, testable processes. It provides a structured approach to writing business operations with:

Explicit inputs with type validation via Solid::Input
Explicit outputs as Solid::Success or Solid::Failure results
Process composition through dependency injection and the Steps DSL
Built-in observability via event logging and instrumentation

The library is designed for progressive mastery: start with simple input/output processes and add sophistication (steps, dependencies, callbacks) as complexity demands.

Sources: README.md42-69 docs/overview/010_KEY_CONCEPTS.md9-25

Core Architecture

The following diagram shows the main architectural components and their relationships using actual class and module names from the codebase:

Sources: Diagram synthesis from README.md1-227 High-Level Architecture Diagrams (provided context)

Core Components

Component	Class/Module	Purpose	Defined In
Process Base	`Solid::Process`	Base class for all business logic processes	lib/solid/process.rb
Input Validation	`Solid::Input`	ActiveModel-based input objects with validation	lib/solid/input.rb
Result Types	`Solid::Success`, `Solid::Failure`	Explicit success/failure outcomes	Provided by `solid-result` gem
Data Modeling	`Solid::Model`	ActiveModel features for data objects	lib/solid/model.rb
Value Objects	`Solid::Value`	Immutable single-value objects	lib/solid/value.rb
Process Execution	`Solid::Process::Caller`	Manages process lifecycle and validation	lib/solid/process/caller.rb
DSL Definition	`Solid::Process::ClassMethods`	Provides `input`, `deps`, steps DSL	lib/solid/process/class_methods.rb
Configuration	`Solid::Process::Config`	Global configuration singleton	lib/solid/process/config.rb
Event Logging	`Solid::Process::EventLogs`	Process execution instrumentation	lib/solid/process/event_logs.rb

Sources: lib/solid/process.rb lib/solid/input.rb lib/solid/model.rb lib/solid/value.rb

Basic Process Structure

Every process inherits from Solid::Process and defines two required components:

Example from codebase:

examples/business_processes/user_creation.rb1-20 demonstrates this structure:

input do ... end block defines attributes and validations
def call(attributes) contains the business logic
Returns Success(:user_created, ...) or Failure(:user_not_created, ...)

Sources: README.md112-139 docs/REFERENCE.md82-155

Process Execution Flow

The following diagram shows how a process executes from invocation through validation to result, using actual method names and module interactions:

Key execution points:

Caller interception - The Solid::Process::Caller module is prepended to intercept call lib/solid/process/caller.rb
Input instantiation - Creates an Input object from raw data lib/solid/process/caller.rb25-35
Validation gate - If input.invalid?, returns Failure(:invalid_input) without executing business logic lib/solid/process/caller.rb37-43
Call execution - If valid, invokes the call method with validated attributes hash lib/solid/process/caller.rb45-50
Result return - Process must return Success(:type, **data) or Failure(:type, **data)

Sources: lib/solid/process/caller.rb Process Execution Flow diagram (provided context)

Dependency Structure

The library depends on two main external dependencies:

Dependency	Version	Purpose
`solid-result`	`~> 2.0`	Provides `Success`/`Failure` result types and event logging infrastructure
`activemodel`	`>= 6.0`	Powers `Solid::Model` with attributes, validations, and callbacks

Sources: solid-process.gemspec42-43

Ruby and Rails Version Support

Solid::Process is tested across a wide compatibility matrix:

Ruby Version	Rails 6.0	Rails 6.1	Rails 7.0	Rails 7.1	Rails 7.2	Rails 8.0	Rails 8.1	Rails Edge
2.7	✅	✅	✅	✅	-	-	-	-
3.0	✅	✅	✅	✅	-	-	-	-
3.1	-	-	✅	✅	✅	-	-	-
3.2	-	-	✅	✅	✅	✅	-	-
3.3	-	-	✅	✅	✅	✅	✅	✅
3.4	-	-	-	-	✅	✅	✅	✅
4.x	-	-	-	-	-	-	✅	✅

This matrix is enforced through the Appraisals-based testing infrastructure. See Multi-Version Testing Strategy for implementation details.

Sources: README.md26-38 Appraisals

Repository Structure

Key directories:

lib/solid/ - Core library code
lib/solid/process/ - Process execution machinery
lib/solid/validators/ - Custom ActiveModel validators
test/solid/ - Comprehensive test suite
docs/ - Documentation including the Reference Guide
examples/ - Real-world example processes
gemfiles/ - Generated Appraisal gemfiles for multi-version testing

Sources: Repository file structure

Key Concepts and Philosophy

Solid::Process embraces emergent design - starting simple and adding sophistication based on actual needs rather than upfront speculation. The development mantra is:

Make it Work - Basic input + call + Success/Failure
Make it Better - Add Steps DSL, validations, normalization
Make it Even Better - Add dependencies, composition, callbacks when complexity demands

This approach reduces over-engineering while providing a clear path for scaling complexity.

For detailed philosophical discussion and design patterns, see Design Patterns and Philosophy.

Sources: docs/overview/010_KEY_CONCEPTS.md31-42 docs/REFERENCE.md43-53

Integration with Rails

While Solid::Process works in pure Ruby applications, it provides specific Rails integrations:

Feature	Description	Module/Method
ActiveRecord Transactions	`rollback_on_failure { }` wraps steps in a transaction	lib/solid/process.rb
Custom Validators	ActiveModel validators: `email`, `uuid`, `id`, `kind_of`, etc.	lib/solid/validators/
ActiveModel Features	Full validation, dirty tracking, callbacks via `Solid::Model`	lib/solid/model.rb
Logger Integration	`BasicLoggerListener` uses `Rails.logger` by default	lib/solid/process/event_logs/basic_logger_listener.rb

For detailed Rails integration patterns, see Rails Integration.

Sources: docs/overview/080_RAILS_INTEGRATION.md lib/solid/validators/

Observable Process Execution

One of Solid::Process's key features is comprehensive observability without code pollution. The EventLogs system captures every step of execution:

Example log output structure:

#0 Account::OwnerCreation
 * Given(uuid:, owner:)
   #1 User::Creation
    * Given(name:, email:, password:)
    * Continue() from method: validate_email
    * Continue(user:) from method: create_user
    * Success(:user_created, user:)
 * Continue(user:) from method: create_owner
 * Success(:account_owner_created, user:, account:)

For configuration and usage details, see Event Logging System.

Sources: lib/solid/process/event_logs.rb docs/REFERENCE.md1307-1401

Testing Infrastructure

The repository maintains 100% test coverage across multiple Ruby and Rails versions using a sophisticated testing matrix:

For detailed testing strategy documentation, see Multi-Version Testing Strategy.

Sources: Appraisals .github/workflows/main.yml bin/matrix

Getting Started

To begin using Solid::Process:

Installation: bundle add solid-process (see README.md95-108)
First Process: Create a class with input and call (see Your First Process)
Learn the Basics: Input validation, Success/Failure results (see Basic Usage and Results and Outcomes)
Progressive Enhancement: Add Steps DSL, dependencies, callbacks as needed (see Steps DSL and Composition, Dependencies and Injection)
Testing: Use dependency injection for isolation (see Testing Patterns and Best Practices)

Sources: README.md80-145 docs/REFERENCE.md1-79

Documentation Resources

Resource	Purpose	Location
README	Quick start, installation, basic examples	README.md
Reference Guide	Complete feature documentation with examples	docs/REFERENCE.md
Overview Docs	Bite-sized topic guides	docs/overview/
Examples	Working code examples	examples/
Solid Rails App	Complete Rails application example	External repository

Sources: README.md147-169

Overview

Purpose and Scope

What is Solid::Process?

Core Architecture

Core Components

Basic Process Structure

Process Execution Flow

Dependency Structure

Ruby and Rails Version Support

Repository Structure

Key Concepts and Philosophy

Integration with Rails

Observable Process Execution

Testing Infrastructure

Getting Started

Documentation Resources

On this page

Overview

Purpose and Scope

What is Solid::Process?

Core Architecture

Core Components

Basic Process Structure

Process Execution Flow

Dependency Structure

Ruby and Rails Version Support

Repository Structure

Key Concepts and Philosophy

Integration with Rails

Observable Process Execution

Testing Infrastructure

Getting Started

Documentation Resources

On this page

Ruby Version	Rails 6.0	Rails 6.1	Rails 7.0	Rails 7.1	Rails 7.2	Rails 8.0	Rails 8.1	Rails Edge
2.7	✅	✅	✅	✅	-	-	-	-
3.0	✅	✅	✅	✅	-	-	-	-
3.1	-	-	✅	✅	✅	-	-	-
3.2	-	-	✅	✅	✅	✅	-	-
3.3	-	-	✅	✅	✅	✅	✅	✅
3.4	-	-	-	-	✅	✅	✅	✅
4.x	-	-	-	-	-	-	✅	✅

Ruby Version	Rails 6.0	Rails 6.1	Rails 7.0	Rails 7.1	Rails 7.2	Rails 8.0	Rails 8.1	Rails Edge
2.7	✅	✅	✅	✅	-	-	-	-
3.0	✅	✅	✅	✅	-	-	-	-
3.1	-	-	✅	✅	✅	-	-	-
3.2	-	-	✅	✅	✅	✅	-	-
3.3	-	-	✅	✅	✅	✅	✅	✅
3.4	-	-	-	-	✅	✅	✅	✅
4.x	-	-	-	-	-	-	✅	✅

Ruby Version	Rails 6.0	Rails 6.1	Rails 7.0	Rails 7.1	Rails 7.2	Rails 8.0	Rails 8.1	Rails Edge
2.7	✅	✅	✅	✅	-	-	-	-
3.0	✅	✅	✅	✅	-	-	-	-
3.1	-	-	✅	✅	✅	-	-	-
3.2	-	-	✅	✅	✅	✅	-	-
3.3	-	-	✅	✅	✅	✅	✅	✅
3.4	-	-	-	-	✅	✅	✅	✅
4.x	-	-	-	-	-	-	✅	✅

Ruby Version	Rails 6.0	Rails 6.1	Rails 7.0	Rails 7.1	Rails 7.2	Rails 8.0	Rails 8.1	Rails Edge
2.7	✅	✅	✅	✅	-	-	-	-
3.0	✅	✅	✅	✅	-	-	-	-
3.1	-	-	✅	✅	✅	-	-	-
3.2	-	-	✅	✅	✅	✅	-	-
3.3	-	-	✅	✅	✅	✅	✅	✅
3.4	-	-	-	-	✅	✅	✅	✅
4.x	-	-	-	-	-	-	✅	✅

Ruby Version	Rails 6.0	Rails 6.1	Rails 7.0	Rails 7.1	Rails 7.2	Rails 8.0	Rails 8.1	Rails Edge
2.7	✅	✅	✅	✅	-	-	-	-
3.0	✅	✅	✅	✅	-	-	-	-
3.1	-	-	✅	✅	✅	-	-	-
3.2	-	-	✅	✅	✅	✅	-	-
3.3	-	-	✅	✅	✅	✅	✅	✅
3.4	-	-	-	-	✅	✅	✅	✅
4.x	-	-	-	-	-	-	✅	✅

Ruby Version	Rails 6.0	Rails 6.1	Rails 7.0	Rails 7.1	Rails 7.2	Rails 8.0	Rails 8.1	Rails Edge
2.7	✅	✅	✅	✅	-	-	-	-
3.0	✅	✅	✅	✅	-	-	-	-
3.1	-	-	✅	✅	✅	-	-	-
3.2	-	-	✅	✅	✅	✅	-	-
3.3	-	-	✅	✅	✅	✅	✅	✅
3.4	-	-	-	-	✅	✅	✅	✅
4.x	-	-	-	-	-	-	✅	✅