Document plugin architecture

README.md

@@ -479,7 +479,7 @@ end
 ```
 
 As you can see above you can also customize the search field (`:search_by`) and indicate if you want to override the result key (`:set_result_key`) when calling to `model`.
-These two options aren't mandatory, and by default pathway will set the search field to the class model primary key, and override the result key to a snake cased version of the model name (ignoring namespaces if contained inside a class or module).
+These two options aren't mandatory, and by default Pathway will set the search field to the class model primary key, and override the result key to a snake cased version of the model name (ignoring namespaces if contained inside a class or module).
 
 Let's now take a look at the provided extensions:
 
@@ -570,6 +570,15 @@ As you can see is almost identical as the previous example only that this time y
 
 ### Plugin architecture
 
+Going a bit deeper now, we'll explain how to implement your own plugins. As was mention before `pathway` follows a very similar approach to the [Roda](http://roda.jeremyevans.net/) or [Sequel](http://sequel.jeremyevans.net/) plugin systems, which is reflected on its implementation.
+
+Each plugin must be defined in a file placed within the `pathway/plugins/` directory of your gem or application, so `pathway` can require the file; and must be implemented as a module inside the `Pathway::Plugins` namespace module. Inside your plugin module, three extra modules can be define to extend the operation API `ClassMethods`, `InstanceMethods` and `DSLMethods`; plus a class method `apply` for plugin initialization when needed.
+
+If you are familiar with the aforementioned plugin mechanism (or other as well), the function of each module is probably starting to feel evident: `ClassMethods` will be used to extend the operation class, so any class methods should be defined here; `InstanceMethods` will be included on the operation so all the instance methods you need to add to the operation should be defined here, this include every custom step you need to add; and finally `DSLMethods` will be included on `Operation::DSL` class, which hold all the DSL methods like `step` or `set`.
+The `apply` method will simply be run whenever the plugin is included taking the operation class on the first argument and also all then arguments the call to `plugin` received (excluding the plugin name).
+
+
+
 ### Testing tools
 
 As of right now only `rspec` is supported, that is, you can obviously test your operations with any framework you want, but all the provided matchers are designed for `rspec`.