trailblazer 1.1.2 → 2.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bcb891f0ed3b87e1bcdf9cc2daae8567bb7cadad
-  data.tar.gz: ca5dfac4197a4fa81b1e5b0f2174dcf0770f00ce
+  metadata.gz: 796e342235352bda7ad6efbfbb4917f016846ff5
+  data.tar.gz: b7f53417cf1b74c08f8177a92f536e2990675dca
 SHA512:
-  metadata.gz: d5507ab87b7ac7a547ec7b720ba03bf01d770dc54930837df6f8c71c355e15432e79a99906aba55eef67ca0495aec98101b3a782142611fad6d91060c846febd
-  data.tar.gz: 509f9d035b11e8f416d2810e2b6977b4d3ce7f7a324460b3cdf63d711f9fc2b28ff15198fde88d394d05569d7a75762f8904a963a9d16bfc34f9e194251543c5
+  metadata.gz: e8a5e6fbdb459b89c6dbf7c97d1771691d4b0ca0e259a27fb6318b977de11ba557b38db00f8816e0d671975ba9a5b58a180771e9d2ecad0d7a6d0d69e0f6bf5a
+  data.tar.gz: f801d455bae0cafa1746c362d435e6ee39b23430836577c908b15904178abc42ba4a3af550ec763ae74328c7042f0bc4ac281bf5d2cf3e16d88ca43978d06bb9

data/.travis.yml

@@ -1,10 +1,13 @@
 language: ruby
-rvm:
-  - 2.2
-  - 2.1
-  - 2.0
-gemfiles:
-  - gemfiles/Gemfile.reform-2.0
-  - gemfiles/Gemfile.reform-2.1
 before_install:
   - gem install bundler
+matrix:
+  include:
+    # - rvm: 2.0.0
+    #   gemfile: "test/gemfiles/Gemfile.ruby-2.0"
+    - rvm: 2.1
+      gemfile: Gemfile
+    - rvm: 2.2
+      gemfile: Gemfile
+    - rvm: 2.3.1
+      gemfile: Gemfile

data/CHANGES.md

@@ -1,3 +1,111 @@
+
+# 2.0.0
+
+## Operation API change:
+
+* You can now have any number of contracts, `contract [:name], constant/block`.
+
+`Contract`, Setup, Model
+expose via `result[:_invocations] = _invocations`
+
+* Changed `Operation#validate`: the signature now is `validate(params, model=self.model, options={}, contract_class)`.
+* Changed `Operation#contract`: the signature now is `contract(model=self.model, options={}, contract_class)`.
+
+Both changes simplify injecting additional dependencies into the contract, or making use of `Composition` contracts. Read more [here](http://trailblazer.to/gems/operation/contract.html). Note that in 1.2, there are deprecation mechanics to handle old code.
+
+* Added `Trailblazer::Builder` for a builder-and-call mechanism decoupled from the operation.
+* Finally removed `Operation::[]`. Be careful, this is now replaced and will return the specified competence.
+
+TRB 1.1
+  build_operation(params).run
+    process(@params)
+TRB 1.2
+  build_operation(params, *).call(params)
+
+* Removed `Operation::reject`. This is available in `trailblazer-compat`.
+* `Operation#invalid!` is now an optional module `Trailblazer::Operation::Invalid`.
+* `Operation::present` is now optional. Include `Present`.
+
+# CHANGES:
+# * Removed `Operation::[]` in favor of `Operation::()`.
+# * `Operation#invalid!` doesn't accept a result anymore.
+# * Removed `Operation#valid?` in favor of the result object.
+#
+
+## Model
+
+* The `model` method doesn't exist anymore, use `self["model"]` or write your own.
+* `find_by` diverts to left track.
+* `:create` is `:new` now.
+
+## DI
+
+You can now inject the following objects via `::call`:
+
+* `"contract.default.class"`
+* `"contract"`: The contract instance.
+* `"model.class"`
+
+* Removed `Operation::run` as it was a bad decision. Raising an exception on invalid is a very test-specific scenario and shouldn't have been handled in the core doce.
+* Removed `Operation::present`, since you can simply call `Operation::new` (without builders) or `Operation::build_operation` (with builders).
+* Removed `Operation::valid?`. This is in the result object via `result[:valid]`.
+* Removed `Operation#errors`. This is in the result object via `result[:errors]` if the operation was invalid.
+* Removed the private option `:raise_on_invalid`. Use `Contract::Raise` instead, if you need it in tests.
+
+* Removed `Operation::contract` (without args). Please use `Operation::["contract.default.class"]`.
+* Removed `Operation::callbacks` (without args). Please use `Operation::["callback.<name>.class"]`.
+* Removed `Operation::contract_class`. Please use `Operation::["contract.default.class"]`.
+* Removed `Operation::contract_class=`. Please use `Operation::["contract.default.class"]=`. Doesn't inherit.
+
+## Builder
+
+* It's `include Builder` now, not `extend Builder`.
+* `builds` now receives one options hash.
+
+## Policy
+
+* No exception anymore, but `Operation#["policy.result"]`.
+* Access the current user via `self["current_user"]` now.
+* `Policy` is `Policy::Pundit` now as `Policy` is Trailblazer's authorization style.
+
+## Representer
+
+* Removed `Operation::representer_class`. Please use `Operation::["representer.class"]`.
+* Removed `Operation::representer_class=`. Please use `Operation::["representer.class"]=`.
+* You can now have any number of named representers: `Operation.representer :parser, ParsingRepresenter`.
+* Automatic infering of the representer from a `contract` is not so automatic anymore. This feature was barely used and is now available via `include Representer::InferFromContract`.
+* Reform 2.0 is not supported in `Representer` anymore, meaning you can't automatically infer representers from 2.0 contracts. Reform 2.0 works with all remaining components.
+* Removed `Operation::contract_class`. Please use `Operation::["contract.default.class"]`.
+* Removed `Operation::contract_class=`. Please use `Operation::["contract.default.class"]=`. Doesn't inherit.
+
+## Callback
+
+* Removed `Operation::Dispatch`, it's called `Operation::Callback`.
+
+## #call
+* You can return whatever you want now by overriding `Op::call`.
+* Removed `Op.call().contract`, you now have to do `Op.call()[:operation].contract`.
+
+
+* Removed the deprecation for `validate`, signature is `(params[, model, options, contract_class])`.
+* Removed the deprecation for `contract`, signature is `([model, options, contract_class])`.
+
+## Collection
+
+* Removed `Operation::Collection`. Please use `Operation::present`.
+
+## Controller
+
+* Removed `Controller#params!`, no one was using it.
+
+## Contract
+
+* You can't call `Create.().contract` anymore. The contract instance(s) are available through the `Result` object.
+
+# 2.0.0.beta1
+
+* Still undefined `self.~`.
+
 # 1.1.2
 
 * Stricter `uber` dependency.

data/COMM-LICENSE

@@ -0,0 +1,91 @@
+END-USER LICENSE AGREEMENT
+
+------------------------------------------------------------------------------
+
+IMPORTANT: THIS SOFTWARE END-USER LICENSE AGREEMENT ("EULA") IS A LEGAL AGREEMENT (“Agreement”) BETWEEN YOU (THE CUSTOMER, EITHER AS AN INDIVIDUAL OR, IF PURCHASED OR OTHERWISE ACQUIRED BY OR FOR AN ENTITY, AS AN ENTITY) AND SYNERGY SOFTWARE SOLUTIONS. READ IT CAREFULLY BEFORE COMPLETING THE INSTALLATION PROCESS AND USING TRAILBLAZER ENTERPRISE AND RELATED SOFTWARE COMPONENTS (“SOFTWARE”). IT PROVIDES A LICENSE TO USE THE SOFTWARE AND CONTAINS WARRANTY INFORMATION AND LIABILITY DISCLAIMERS. BY INSTALLING AND USING THE SOFTWARE, YOU ARE CONFIRMING YOUR ACCEPTANCE OF THE SOFTWARE AND AGREEING TO BECOME BOUND BY THE TERMS OF THIS AGREEMENT.
+
+------------------------------------------------------------------------------
+
+In order to use the Software under this Agreement, you must receive a “Source URL” at the time of purchase, in accordance with the scope of use and other terms specified for each type of Software and as set forth in this Section 1 of this Agreement.
+
+1. License Grant
+
+1.1 General Use. This Agreement grants you a non-exclusive, non-transferable, limited license to the use rights for the Software, without the right to grant sublicenses, subject to the terms and conditions in this Agreement. The Software is licensed, not sold.
+
+1.3 Limited Organization License. If you purchased an Organization License (included with the Trailblazer Enterprise Software), you may install the Software on an unlimited number of Hosts. “Host” means any physical or virtual machine which is controlled by you.
+
+1.4 Appliance License. If you purchased an Appliance License, you may distribute the Software in any applications, frameworks, or elements (collectively referred to as an “Application” or “Applications”) that you develop using the Software in accordance with this EULA, provided that such distribution does not violate the restrictions set forth in section 3 of this EULA. You must not remove, obscure or interfere with any copyright, acknowledgment, attribution, trademark, warning or disclaimer statement affixed to, incorporated in or otherwise applied in connection with the Software. You are required to ensure that the Software is not reused by or with any applications other than those with which you distribute it as permitted herein. For example, if You install the Software on a customer’s server, that customer is not permitted to use the Software independently of your Application. You must inform Synergy Software Solutions of your knowledge of any infringing use of the Software by any of your customers. You are liable for compliance by those third parties with the terms and conditions of this EULA. You will not owe Synergy Software Solutions any royalties for your distribution of the Software in accordance with this EULA.
+
+1.5 Archive Copies. You are entitled to make a reasonable amount of copies of the Software for archival purposes. Each copy must reproduce all copyright and other proprietary rights notices on or in the Software Product.
+
+1.6 Electronic Delivery. All Software and license documentation shall be delivered by electronic means unless otherwise specified on the applicable invoice or at the time of purchase. Software shall be deemed delivered when it is made available for download by you (“Delivery”).
+
+2. Modifications. Synergy Software Solutions shall provide you with source code so that you can create Modifications of the original software. “Modification” means: (a) any addition to or deletion from the contents of a file included in the original Software or previous Modifications created by You, or (b) any new file that contains any part of the original Software or previous Modifications. While you retain all rights to any original work authored by you as part of the Modifications, We continue to own all copyright and other intellectual property rights in the Software.
+
+3. Restricted Uses.
+
+3.1 You shall not (and shall not allow any third party to): (a) decompile, disassemble, or otherwise reverse engineer the Software or attempt to reconstruct or discover any source code, underlying ideas, algorithms, file formats or programming interfaces of the Software by any means whatsoever (except and only to the extent that applicable law prohibits or restricts reverse engineering restrictions); (b) distribute, sell, sublicense, rent, lease or use the Software for time sharing, hosting, service provider or like purposes, except as expressly permitted under this Agreement; (c) redistribute the Software or Modifications other than by including the Software or a portion thereof within your own product, which must have substantially different functionality than the Software or Modifications and must not allow any third party to use the Software or Modifications, or any portions thereof, for software development or application development purposes; (d) redistribute the Software as part of a product, "appliance" or "virtual server"; (e) redistribute the Software on any server which is not directly under your control; (f) remove any product identification, proprietary, copyright or other notices contained in the Software; (g) modify any part of the Software, create a derivative work of any part of the Software (except as permitted in Section 4), or incorporate the Software, except to the extent expressly authorized in writing by Synergy Software Solutions; (h) publicly disseminate performance information or analysis (including, without limitation, benchmarks) from any source relating to the Software; (i) utilize any equipment, device, software, or other means designed to circumvent or remove any form of Source URL or copy protection used by Synergy Software Solutions in connection with the Software, or use the Software together with any authorization code, Source URL, serial number, or other copy protection device not supplied by Synergy Software Solutions; (j) use the Software to develop a product which is competitive with any Synergy Software Solutions product offerings; or (k) use unauthorized Source URLS or keycode(s) or distribute or publish Source URLs or keycode(s), except as may be expressly permitted by Synergy Software Solutions in writing. If your unique Source URL is ever published, Synergy Software Solutions reserves the right to terminate your access without notice.
+
+3.2 UNDER NO CIRCUMSTANCES MAY YOU USE THE SOFTWARE AS PART OF A PRODUCT OR SERVICE THAT PROVIDES SIMILAR FUNCTIONALITY TO THE SOFTWARE ITSELF.
+
+The Open Source version of the Software (“LGPL Version”) is licensed
+under the terms of the GNU Lesser General Public License versions 3.0
+(“LGPL”) and not under this EULA.
+
+4. Ownership. Notwithstanding anything to the contrary contained herein, except for the limited license rights expressly provided herein, Synergy Software Solutions and its suppliers have and will retain all rights, title and interest (including, without limitation, all patent, copyright, trademark, trade secret and other intellectual property rights) in and to the Software and all copies, modifications and derivative works thereof (including any changes which incorporate any of your ideas, feedback or suggestions). You acknowledge that you are obtaining only a limited license right to the Software, and that irrespective of any use of the words “purchase”, “sale” or like terms hereunder no ownership rights are being conveyed to you under this Agreement or otherwise.
+
+5. Fees and Payment. The Software license fees will be due and payable in full as set forth in the applicable invoice or at the time of purchase. If the Software does not function properly within two weeks of purchase, please contact us within those two weeks for a refund. You shall be responsible for all taxes, withholdings, duties and levies arising from the order (excluding taxes based on the net income of Synergy Software Solutions).
+
+6. Support, Maintenance and Services. Subject to the terms and conditions of this Agreement, as set forth in your invoice, and as set forth on the Trailblazer Enterprise support page (http://enterprise.trailblazer.to), support and maintenance services may be included with the purchase of your license subscription.
+
+7. Term of Agreement.
+
+7.1 Term. This Agreement is effective as of the Delivery of the Software and expires at such time as all license and service subscriptions hereunder have expired in accordance with their own terms (the “Term”). For clarification, the term of your license under this Agreement may be perpetual, limited for Evaluation Version, or designated as a fixed-term license in the Invoice, and shall be specified at your time of purchase. Either party may terminate this Agreement (including all related Invoices) if the other party: (a) fails to cure any material breach of this Agreement within thirty (30) days after written notice of such breach, provided that Synergy Software Solutions may terminate this Agreement immediately upon any breach of Section 3 or if you exceed any other restrictions contained in Section 1, unless otherwise specified in this agreement; (b) ceases operation without a successor; or (c) seeks protection under any bankruptcy, receivership, trust deed, creditors arrangement, composition or comparable proceeding, or if any such proceeding is instituted against such party (and not dismissed within sixty (60) days)). Termination is not an exclusive remedy and the exercise by either party of any remedy under this Agreement will be without prejudice to any other remedies it may have under this Agreement, by law, or otherwise.
+
+7.2 Termination. Upon any termination of this Agreement, you shall cease any and all use of any Software and destroy all copies thereof.
+
+7.3 Expiration of License. Upon the expiration of any term under this Agreement, (a) all Software updates and services pursuant to the license shall cease, (b) you may only continue to run existing installations of the Software, (c) you may not install the Software on any additional Hosts, and (d) any new installation of the Software shall require the purchase of a new license subscription from Synergy Software Solutions.
+
+8. Disclaimer of Warranties. The Software is provided "as is," with all faults, defects and errors, and without warranty of any kind. Synergy Software Solutions does not warrant that the Software will be free of bugs, errors, viruses or other defects, and Synergy Software Solutions shall have no liability of any kind for the use of or inability to use the Software, the Software content or any associated service, and you acknowledge that it is not technically practicable for Synergy Software Solutions to do so.
+To the maximum extent permitted by applicable law, Synergy Software Solutions disclaims all warranties, express, implied, arising by law or otherwise, regarding the Software, the Software content and their respective performance or suitability for your intended use, including without limitation any implied warranty of merchantability, fitness for a particular purpose.
+
+9. Limitation of Liability.
+
+In no event will Synergy Software Solutions be liable for any direct, indirect, consequential, incidental, special, exemplary, or punitive damages or liabilities whatsoever arising from or relating to the Software, the Software content or this Agreement, whether based on contract, tort (including negligence), strict liability or other theory, even if Synergy Software Solutions has been advised of the possibility of such damages.
+
+In no event will Synergy Software Solutions' liability exceed the Software license price as indicated in the invoice. The existence of more than one claim will not enlarge or extend this limit.
+
+10. Remedies. Your exclusive remedy and Synergy Software Solutions’ entire liability for breach of this Agreement shall be limited, at Synergy Software Solutions’ sole and exclusive discretion, to (a) replacement of any defective software or documentation; or (b) refund of the license fee paid to Synergy Software Solutions, payable in accordance with Synergy Software Solutions' refund policy.
+
+11. Acknowledgements.
+
+11.1 Consent to the Use of Data. You agree that Synergy Software Solutions and its affiliates may collect and use technical information gathered as part of the product support services. Synergy Software Solutions may use this information solely to improve products and services and will not disclose this information in a form that personally identifies you.
+
+11.3 Government End Users. If the Software and related documentation are supplied to or purchased by or on behalf of the United States Government, then the Software is deemed to be "commercial software" as that term is used in the Federal Acquisition Regulation system. Rights of the United States shall not exceed the minimum rights set forth in FAR 52.227-19 for "restricted computer software". All other terms and conditions of this Agreement apply.
+
+12. Third Party Software.  Examples included in Software may provide links to third party libraries or code (collectively “Third Party Software”) to implement various functions. Third Party Software does not comprise part of the Software. In some cases, access to Third Party Software may be included along with the Software delivery as a convenience for demonstration purposes. Such source code and libraries may be included in the “…/examples” source tree delivered with the Software and do not comprise the Software. Licensee acknowledges (1) that some part of Third Party Software may require additional licensing of copyright and patents from the owners of such, and (2) that distribution of any of the Software referencing or including any portion of a Third Party Software may require appropriate licensing from such third parties.
+
+
+13. Miscellaneous
+
+13.1 Entire Agreement. This Agreement sets forth our entire agreement with respect to the Software and the subject matter hereof and supersedes all prior and contemporaneous understandings and agreements whether written or oral.
+
+13.2 Amendment. Synergy Software Solutions reserves the right, in its sole discretion, to amend this Agreement from time. Amendments to this Agreement can be located at: https://github.com/trailblazer/trailblazer/blob/master/COMM-LICENSE.
+
+13.3 Assignment. You may not assign this Agreement or any of its rights under this Agreement without the prior written consent of Synergy Software Solutions and any attempted assignment without such consent shall be void.
+
+13.4 Export Compliance. You agree to comply with all applicable laws and regulations, including laws, regulations, orders or other restrictions on export, re-export or redistribution of software.
+
+13.5 Indemnification. You agree to defend, indemnify, and hold harmless Synergy Software Solutions from and against any lawsuits, claims, losses, damages, fines and expenses (including attorneys' fees and costs) arising out of your use of the Software or breach of this Agreement.
+
+13.6 Governing Law. This Agreement is governed by the laws of the State of Oregon and the United States without regard to conflicts of laws provisions thereof, and without regard to the United Nations Convention on the International Sale of Goods or the Uniform Computer Information Transactions Act, as currently enacted by any jurisdiction or as may be codified or amended from time to time by any jurisdiction. The jurisdiction and venue for actions related to the subject matter hereof shall be the state of Oregon and United States federal courts located in Portland, Oregon, and both parties hereby submit to the personal jurisdiction of such courts.
+
+13.7 Attorneys’ Fees and Costs. The prevailing party in any action to enforce this Agreement will be entitled to recover its attorneys’ fees and costs in connection with such action.
+
+13.8 Severability. If any provision of this Agreement is held by a court of competent jurisdiction to be invalid, illegal, or unenforceable, the remainder of this Agreement will remain in full force and effect.
+
+13.9 Waiver. Failure or neglect by either party to enforce at any time any of the provisions of this licence Agreement shall not be construed or deemed to be a waiver of that party's rights under this Agreement.
+
+13.10 Headings. The headings of sections and paragraphs of this Agreement are for convenience of reference only and are not intended to restrict, affect or be of any weight in the interpretation or construction of the provisions of such sections or paragraphs.
+
+14. Contact Information. If you have any questions about this EULA, or if you want to contact Synergy Software Solutions for any reason, please direct correspondence to info@trailblazer.to.

data/Gemfile

@@ -5,10 +5,24 @@ gemspec
 
 # gem "representable", path: "../representable"
 # gem "disposable", path: "../disposable"
-gem "virtus"
-gem "reform", github: "apotonick/reform"
+# gem "reform", github: "apotonick/reform"
+gem "reform-rails"
+gem "activesupport", "~> 4.2.0"
+
 gem "roar", github: "apotonick/roar"
 # gem "reform", "~> 2.0.0"
-# gem "reform", path: "../reform"
+gem "reform"#, path: "../reform"
 # gem "roar", path: "../roar"
-gem "multi_json"
+gem "multi_json"
+
+gem "dry-auto_inject"
+gem "dry-matcher"
+gem "dry-validation"
+
+
+# gem "trailblazer-operation", path: "../operation"
+gem "pipetree"#, path: "../pipetree"
+
+gem "minitest-line"
+
+# gem "uber", path: "../uber"

data/LICENSE.txt

@@ -1,22 +1,9 @@
-Copyright (c) 2013 Nick Sutterer
+Copyright (c) Nick Sutterer
 
-MIT License
+Trailblazer is an Open Source project licensed under the terms of
+the LGPLv3 license.  Please see <http://www.gnu.org/licenses/lgpl-3.0.html>
+for license text.
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Trailblazer Enterprise has a commercial-friendly license allowing private forks
+and modifications of Trailblazer.  Please see http://trailblazer.to/enterprise/ for
+more detail.  You can find the commercial license terms in COMM-LICENSE.

data/README.md

@@ -6,11 +6,12 @@ _Trailblazer is a thin layer on top of Rails. It gently enforces encapsulation,
 [![TRB Newsletter](https://img.shields.io/badge/TRB-newsletter-lightgrey.svg)](http://trailblazer.to/newsletter/)
 [![Gem Version](https://badge.fury.io/rb/trailblazer.svg)](http://badge.fury.io/rb/trailblazer)
 
+**This document discusses Trailblazer 2.0. The [1.x documentation is here](http://trailblazer.to/gems/operation/1.1/).**
 
 ## Trailblazer In A Nutshell
 
 1. All business logic is encapsulated in [operations](#operation) (service objects).
-  * An optional Reform [form](#validations) object in the operation deserializes and validates input. The form object can also be used for rendering.
+  * Optional [validation objects](#validation) (Reform and/or Dry-validation) in the operation deserialize and validate input. The form object can also be used for rendering.
   * An optional [policy](#policies) object blocks unauthorized users from running the operation.
   * Optional [callback](#callbacks) objects allow declaring post-processing logic.
 3. [Controllers](#controllers) instantly delegate to an operation. No business code in controllers, only HTTP-specific logic.
@@ -19,7 +20,7 @@ _Trailblazer is a thin layer on top of Rails. It gently enforces encapsulation,
 
 Trailblazer is designed to handle different contexts like user roles by applying [inheritance](#inheritance) between and [composing](#composing) of operations, form objects, policies, representers and callbacks.
 
-Wanna see some code? Jump [right here](#controllers)!
+Want code? Jump [right here](#controllers)!
 
 ## Mission
 
@@ -42,25 +43,37 @@ Since Trailblazer decouples the High-Level Stack from the framework, it runs wit
 * Trailblazer with Grape - coming _very_ soon!
 
 
-## A Concept-Driven OOP Framework
+## Concepts over Technology
 
-Trailblazer offers you a new, more intuitive file layout in Rails apps where you structure files by *concepts*.
+Trailblazer offers you a new, more intuitive file layout in applications.
 
 ```
 app
 ├── concepts
 │   ├── comment
-│   │   ├── cell.rb
-│   │   ├── views
+│   │   ├── operation
+│   │   │   ├── create.rb
+│   │   │   ├── update.rb
+│   │   ├── contract
+│   │   │   ├── create.rb
+│   │   │   ├── update.rb
+│   │   ├── cell
+│   │   │   ├── show.rb
+│   │   │   ├── index.rb
+│   │   ├── view
 │   │   │   ├── show.haml
-│   │   │   ├── list.haml
-│   │   ├── assets
+│   │   │   ├── index.rb
 │   │   │   ├── comment.css.sass
-│   │   ├── operation.rb
-│   │   ├── twin.rb
 ```
 
-Files, classes and views that logically belong to one _concept_ are kept in one place. You are free to use additional namespaces within a concept. Trailblazer tries to keep it as simple as possible, though.
+Instead of grouping by technology, classes and views are structured by *concept*, and then by technology. A concept can relate to a model, or can be a completely abstract concern such as `invoicing`.
+
+Within a concept, you can have any level of nesting. For example, `invoicing/pdf/` could be one.
+
+The file structure is implemented by the [`trailblazer-loader` gem](https://github.com/trailblazer/trailblazer-loader).
+
+[Learn more.](http://trailblazer.to/gems/trailblazer/loader.html)
+
 
 ## Architecture
 
@@ -89,6 +102,7 @@ class CommentsController < ApplicationController
   def create
     run Comment::Create # Comment::Create is an operation class.
   end
+end
 ```
 
 The `#run` method invokes the operation. It allows you to run a conditional block of logic if the operation was successful.
@@ -102,6 +116,7 @@ class CommentsController < ApplicationController
 
     render :new # invalid. re-render form.
   end
+end
 ```
 
 Again, the controller only dispatchs to the operation and handles successful/invalid processing on the HTTP level. For instance by redirecting, setting flash messages, or signing in a user.
@@ -112,9 +127,11 @@ Again, the controller only dispatchs to the operation and handles successful/inv
 
 Operations encapsulate business logic and are the heart of a Trailblazer architecture.
 
-Operations don't know about HTTP or the environment. You could use an operation in Rails, Hanami, or Roda, it wouldn't know. This makes them an ideal replacement for test factories.
+The bare bones operation without any Trailblazery is implemented in [the `trailblazer-operation` gem[(https://github.com/trailblazer/trailblazer-operation) and can be used without our stack.
 
-An operation is not just a monolithic replacement for your business code. It's a simple orchestrator between the form object, models and your business code.
+Operations don't know about HTTP or the environment. You could use an operation in Rails, Hanami, or Roda, it wouldn't know.
+
+An operation is not just a monolithic replacement for your business code. It's a simple orchestrator between the form objects, models, your business code and all other layers needed to get the job done.
 
 ```ruby
 class Comment::Create < Trailblazer::Operation
@@ -124,14 +141,26 @@ class Comment::Create < Trailblazer::Operation
 end
 ```
 
-Operations only need to implement `#process` which receives the params from the caller.
+Operations only need to implement `#process` which receives the arguments from the caller.
+
+You cannot instantiate them per design. The only way to invoke them is `call`.
+
+```ruby
+Comment::Create.call(whatever: "goes", in: "here")
+# same as
+Comment::Create.(whatever: "goes", in: "here")
+```
+
+Their high degree of encapsulation makes them a [replacement for test factories](#test), too.
 
 [Learn more.](http://trailblazer.to/gems/operation)
 
-## Validations
+## Validation
 
 In Trailblazer, an operation (usually) has a form object which is simply a `Reform::Form` class. All the [API documented in Reform](https://github.com/apotonick/reform) can be applied and used.
 
+Validations can also be implemented in pure Dry-validation.
+
 The operation makes use of the form object using the `#validate` method.
 
 ```ruby
@@ -169,6 +198,7 @@ class Comment::Create < Trailblazer::Operation
   callback(:after_save) do
     on_change :markdownize_body! # this is only run when the form object has changed.
   end
+end
 ```
 
 Callbacks are never triggered automatically, you have to invoke them! This is called _Imperative Callback_.
@@ -232,12 +262,19 @@ class Comment::Create < Trailblazer::Operation
   include Policy
 
   policy Comment::Policy, :create?
+end
 ```
 
 The policy is evaluated in `#setup!`, raises an exception if `false` and suppresses running `#process`.
 
 [Learn more.](http://trailblazer.to/gems/operation/policy.html)
 
+## Pipetree
+
+The operation code is not supposed to be procedural, but in form of a function pipeline. You can still write procedural code with stacked methods calls where ever you want, e.g. in `process`.
+
+However, a much smarter way to chain logic is to use the *pipetree*.
+
 ## Views
 
 View rendering can happen using the controller as known from Rails. This is absolutely fine for simple views.
@@ -251,6 +288,7 @@ class CommentsController < ApplicationController
   def new
     form Comment::Create # will assign the form object to @form.
   end
+end
 ```
 
 Since Reform objects can be passed to form builders, you can use the operation to render and process the form!
@@ -275,6 +313,7 @@ class Comment::Create < Trailblazer::Operation
 
     link(:self) { comment_path(represented.id) }
   end
+end
 ```
 
 The operation can then parse incoming JSON documents in `validate` and render a document via `to_json`.
@@ -290,6 +329,7 @@ Operations completely replace the need for leaky factories.
 ```ruby
 describe Comment::Update do
   let(:comment) { Comment::Create.(comment: {body: "[That](http://trailblazer.to)!"}) }
+end
 ```
 
 ## More