# animikii/makwa architecture

> Architecture diagram of the GitHub repository animikii/makwa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/animikii/makwa
- Repository: https://github.com/animikii/makwa

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Rails Application Layer
    subgraph "Rails Application" 
        direction TB
        Controller["Controllers"]:::app
        ViewForm["Views/Forms"]:::app
        ARModel["ActiveRecord Models"]:::app
    end

    %% Makwa Gem Layer
    subgraph "Makwa Gem" 
        direction TB
        CoreModule["Makwa Core Module"]:::gem
        BaseInteraction["BaseInteraction"]:::gem
        ReturningInteraction["ReturningInteraction"]:::gem
        ErrorUtils["Error-handling Utilities"]:::gem
        Logging["Logging Facility"]:::gem
        Version["Version"]:::gem
        Gemspec["Gem Specification & Packaging"]:::gem
        BuildTasks["Dependency & Build Task Definitions"]:::gem
        BinScripts["Developer CLI Scripts"]:::gem
        Documentation["Documentation"]:::doc
        Tests["Unit Tests"]:::test
    end

    %% Dependencies & External
    subgraph "Dependencies & External"
        direction TB
        ActiveInteraction["ActiveInteraction Engine"]:::dep
        Database["Database"]:::dep
        ExternalService["External Service (e.g., SendEmail)"]:::ext
    end

    %% Data Flow & Relationships
    Controller -->|"run_returning!({user:…})"| ReturningInteraction
    ReturningInteraction -->|"delegates to"| ActiveInteraction
    ReturningInteraction -->|"execute_returning"| ARModel
    ARModel -->|"save/update"| Database
    ReturningInteraction -->|"compose(...) "| ExternalService
    ARModel -->|"errors.merge!"| Controller
    Controller -->|renders| ViewForm

    %% Internal Gem Relationships
    CoreModule --> BaseInteraction
    CoreModule --> ReturningInteraction
    ReturningInteraction --> ErrorUtils
    ReturningInteraction --> Logging
    CoreModule --> Version
    Gemspec -->|defines| CoreModule
    BuildTasks -->|tasks for| CoreModule
    BinScripts -->|setup| CoreModule
    Documentation -->|describes| CoreModule
    Tests -->|validate| BaseInteraction
    Tests -->|validate| ReturningInteraction

    %% Click Events
    click CoreModule "https://github.com/animikii/makwa/blob/main/lib/makwa.rb"
    click BaseInteraction "https://github.com/animikii/makwa/blob/main/lib/makwa/interaction.rb"
    click ReturningInteraction "https://github.com/animikii/makwa/blob/main/lib/makwa/returning_interaction.rb"
    click Version "https://github.com/animikii/makwa/blob/main/lib/makwa/version.rb"
    click Gemspec "https://github.com/animikii/makwa/blob/main/makwa.gemspec"
    click BuildTasks "https://github.com/animikii/makwa/tree/main/Gemfile"
    click BuildTasks "https://github.com/animikii/makwa/tree/main/Rakefile"
    click BinScripts "https://github.com/animikii/makwa/tree/main/bin/console"
    click BinScripts "https://github.com/animikii/makwa/tree/main/bin/setup"
    click Documentation "https://github.com/animikii/makwa/tree/main/doc/"
    click Tests "https://github.com/animikii/makwa/blob/main/test/makwa/interaction_test.rb"
    click Tests "https://github.com/animikii/makwa/blob/main/test/makwa/returning_interaction_test.rb"
    click Tests "https://github.com/animikii/makwa/blob/main/test/test_helper.rb"
    click Readme "https://github.com/animikii/makwa/blob/main/README.md"
    click Changelog "https://github.com/animikii/makwa/blob/main/CHANGELOG.md"
    click License "https://github.com/animikii/makwa/blob/main/LICENSE.txt"

    %% Styles
    classDef app fill:#E3F2FD,stroke:#2196F3,color:#0D47A1,stroke-width:1px
    classDef gem fill:#F3E5F5,stroke:#9C27B0,color:#4A148C,stroke-width:1px
    classDef dep fill:#E8F5E9,stroke:#43A047,color:#1B5E20,stroke-width:1px
    classDef ext fill:#FFF3E0,stroke:#FB8C00,color:#E65100,stroke-width:1px
    classDef doc fill:#FBE9E7,stroke:#FF5722,color:#BF360C,stroke-width:1px
    classDef test fill:#ECEFF1,stroke:#607D8B,color:#263238,stroke-width:1px
```
