How animikii/makwa works
Project type and purpose
• Makwa is an open-source Ruby gem that extends the ActiveInteraction library to improve ergonomics around mutating ActiveRecord instances in Rails apps.
• It provides a new “ReturningInteraction” abstraction, error-handling utilities, early-exit support, and detailed logging.
File structure
Top-level files & directories:
• bin/console, bin/setup – developer scripts for REPL and project setup
• lib/makwa/ – the core library:
– interaction.rb – base classes/mixins for interactions
– returning_interaction.rb – implementation of the ReturningInteraction
– version.rb – gem version
• makwa.gemspec, Gemfile, Rakefile – gem packaging, dependencies, build tasks
• doc/ – documentation: usage examples, design considerations, release process
• test/ – unit tests for interaction and returning_interaction
• README.md, CHANGELOG.md, LICENSE.txt – project metadata
README for additional insights
• Lists key features: ReturningInteraction, safe error checks, early exit, detailed logging.
• Shows example hand-off between Rails controller, interaction, and ActiveRecord model.
• Mentions composition of interactions (compose method) and integration with external systems (e.g., email service).
a. Main components
1. Rails Application (your app)
– Controllers (invoke interactions)
– Views/Forms (render AR models with merged errors)
– ActiveRecord Models (User, etc.)
2. Makwa Gem
– Core Module (Makwa namespace)
– BaseInteraction (extensions on ActiveInteraction)
– ReturningInteraction (specialized class)
– Error-handling utilities (#errors_empty?, #return_if_errors!)
– Logging facility
3. ActiveInteraction Gem (third-party dependency)
4. ActiveRecord & Database
5. External Services
– E.g., Infrastructure::SendEmail or any other composed interaction
b. Relationships & data flow
1. Rails Controller calls Makwa::ReturningInteraction.run_returning!
2. run_returning! delegates to ActiveInteraction execution engine
3. execute_returning logic updates ActiveRecord Model
4. Errors (validation or custom) get merged back into the AR instance
5. Optional compose() calls spin off other interactions (e.g., email sender)
6. Final AR instance (with changes and errors) flows back to Controller → View
7. Database commits on save/update inside interactions
c. Architectural patterns & design principles
– Service Object pattern (interactions encapsulate business logic)
– Composition over inheritance (compose nested interactions)
– Dependency injection (pass AR instance into interaction)
– Single Responsibility (separate validation, persistence, side-effects)
– Fail-fast / early exit (#return_if_errors!)
d. Key technologies & libraries
– Ruby ≥2.7, Rails ≥5
– ActiveInteraction (core engine)
– ActiveRecord (ORM)
– Rake, Bundler, RubyGems