workarea 3.4.12

data/docs/source/articles/orders.html.md

@@ -0,0 +1,66 @@
+---
+title: Orders
+excerpt: 'Workarea applications facilitate orders: transactions between consumers and retailers. Due to their complexity, orders are enabled by and recorded across many models within the Workarea platform. More specifically, various models within the Order, Shi'
+---
+
+# Orders
+
+Workarea applications facilitate <dfn>orders</dfn>: transactions between consumers and retailers. Due to their complexity, orders are enabled by and recorded across many models within the Workarea platform. More specifically, various models within the `Order`, `Shipping`, `Payment`, `Pricing`, `Inventory`, and `Fulfillment` modules enable and record these transactions.
+
+However, at the core of each of these transaction is an `Order` model. The order model uniquely identifies the transaction, and using its `id`, you can join the various models, providing a complete record of the transaction.
+
+## Seeding Order Data
+
+Workarea provides [seeds](seeds.html) for orders, which are defined in `Workarea::OrdersSeeds`. This seeds script creates a variety of placed orders, as well as the user, shipping, and payment data needed to place those orders.
+
+Each order is placed through <dfn>checkout</dfn>, a process that joins an order with the other models necessary to represent a complete consumer/retailer transaction.
+
+Finally, the script _fulfills_ each order, which involves capturing the associated payment and marking the items shipped.
+
+## Joining Order Data
+
+Using the first seeded order as its subject, the following example demonstrates how you can join an order model with the corresponding shippings, payment, inventory transactions, and fulfillment. In practice, this sort of in-application join is typically performed in a [view model](view-models.html).
+
+```
+order = Workarea::Order.first
+
+shippings = Workarea::Shipping.where(order_id: order.id).to_a
+# => [#<Workarea::Shipping _id: 5a95ab0707dd423bb63a92d0, ...>]
+
+payment = Workarea::Payment.find(order.id)
+# => #<Workarea::Payment _id: 048E031F8B, ...>
+
+inventory_transactions =
+  Workarea::Inventory::Transaction.where(order_id: order.id).to_a
+# => [#<Workarea::Inventory::Transaction _id: 5a95ab0a07dd423bb63a931, ...>]
+
+fulfillment = Workarea::Fulfillment.find(order.id)
+# => #<Workarea::Fulfillment _id: 048E031F8B, ...>
+```
+
+## The Order Module
+
+As you can see in the example above, the `id` of the Order model is what relates the various models. Central to order modeling is the `Order` module and its primary models: `Order` and `Order::Item`.
+
+The following order module topics are pertinent to Workarea application and plugin developers:
+
+- [The _order_ and _order item_ abstractions](orders-and-items.html)
+  - What they represent
+  - How they are structured
+- Order statuses and states
+- Managing carts
+- Indexing and searching for orders
+- Managing placed orders
+- Exporting orders
+- Canceling orders
+- Copying orders
+- Order reporting and insights
+- Extending orders
+
+## Summary
+
+- Orders are transactions between consumers and retailers, which are represented by various models within the Workarea platform
+- The model central to a consumer/retailer transaction is `Order`; its `id` joins the other models
+- The platform provides seeds to bootstrap an environment with placed orders
+- Forthcoming guides will explain the order and item abstractions and the various uses of orders within the platform
+

data/docs/source/articles/overriding.html.md

@@ -0,0 +1,155 @@
+---
+title: Overriding
+excerpt: Overriding is a UI extension technique where an application replaces views and assets from the platform with its own customized copies of the files. The replacement files—called overrides—allow HTML, CSS, and JavaScript sent to the browser to be exten
+---
+
+# Overriding
+
+<dfn>Overriding</dfn> is a UI extension technique where an application _replaces_ views and assets from the platform with its own customized copies of the files. The replacement files—called <dfn>overrides</dfn>—allow HTML, CSS, and JavaScript sent to the browser to be extensively customized by the application.
+
+An application can override platform views, layouts, and partials, as well as platform files served by the asset pipeline, such as stylesheets, JavaScript files, images, and fonts.
+
+To override any of these files, simply copy the file to the same path within your application. Rails will render or serve your override instead of the original file from the platform. This works because when resolving paths, Action View and Sprockets both look for files within your application before looking in any Rails engines, including the Workarea engines.
+
+## Example
+
+UI customizations can be extensive, but I'll use a simple example to demonstrate the concept of overriding. By default, product pages in the Storefront display recommendations below the full product description. Refer to the following image.
+
+![Storefront product page before overriding](images/storefront-product-before-overriding.png)
+
+The following example overrides the _products#show_ view in order to change the rendered HTML, moving the recommendations _above_ the product description.
+
+### Identify the File to Override
+
+Before you can create an override, you must identify the file you want to customize. In my case, the file is _app/views/workarea/storefront/products/show.html.haml_. I know this from experience, but there are a variety of ways to search for the file if you are less familiar with the composition of the Storefront.
+
+For example, you can tail the Rails log while browsing to the page of interest. The following example demonstrates a simple search on the log to list recently rendered Haml files.
+
+```bash
+$ tail -f log/development.log | grep 'haml'
+Rendered vendor/ruby/2.4.0/gems/workarea-reviews-2.1.0/app/views/workarea/storefront/products/_rating.html.haml (20.2ms)
+Rendered vendor/ruby/2.4.0/gems/workarea-reviews-2.1.0/app/views/workarea/storefront/products/_reviews_summary.html.haml (35.0ms)
+Rendered vendor/ruby/2.4.0/gems/workarea-clothing-2.1.0/app/views/workarea/storefront/products/_clothing_summary.html.haml (7.1ms)
+Rendered vendor/ruby/2.4.0/gems/workarea-storefront-3.1.1/app/views/workarea/storefront/products/_summary.html.haml (274.9ms)
+Rendered vendor/ruby/2.4.0/gems/workarea-storefront-3.1.1/app/views/workarea/storefront/recent_views/show.html.haml (329.8ms)
+Rendering vendor/ruby/2.4.0/gems/workarea-storefront-3.1.1/app/views/workarea/storefront/products/show.html.haml within layouts/workarea/storefront/application
+Rendered vendor/ruby/2.4.0/gems/workarea-storefront-3.1.1/app/views/workarea/storefront/products/_price.html.haml (5.8ms)
+Rendered vendor/ruby/2.4.0/gems/workarea-storefront-3.1.1/app/views/workarea/storefront/products/_pricing.html.haml (19.7ms)
+# ...
+```
+
+Or, inspect the DOM for a unique string, and search for that string within all installed Workarea engines. In my example, I observed the class value _product-detail-container_, which seemed like a good search term. As shown below, this reduced the list of candidates to three files (two of them views), a small enough set to review manually.&nbsp;<sup><a href="#notes" id="note-1-context">[1]</a></sup>
+
+```bash
+$ grep -lr 'product-detail-container' $(bundle show --paths | grep 'workarea')</kbd>
+/vagrant/board-game-supercenter/vendor/ruby/2.4.0/gems/workarea-package_products-3.1.0/app/views/workarea/storefront/products/package_show.html.haml
+/vagrant/board-game-supercenter/vendor/ruby/2.4.0/gems/workarea-storefront-3.1.1/app/assets/stylesheets/workarea/storefront/components/_product_detail_container.scss
+/vagrant/board-game-supercenter/vendor/ruby/2.4.0/gems/workarea-storefront-3.1.1/app/views/workarea/storefront/products/show.html.haml
+```
+
+### Copy the File into Your Application
+
+Next, I create the necessary directory structure and copy the file into my application. The file path, relative to the engine root, is identical within the Storefront engine and my application.
+
+```bash
+$ mkdir -p app/views/workarea/storefront/products
+$ cp vendor/ruby/2.4.0/gems/workarea-storefront-3.1.1/app/views/workarea/storefront/products/show.html.haml app/views/workarea/storefront/products
+```
+
+The override has now effectively replaced the original Storefront file, but the files are identical, so there is no observable difference in the application. It is a good idea to commit the new file to your application repository before changing it, so that the introduction of the file and the changes you make to it are recorded separately in your repository history.
+
+```bash
+$ git commit -m 'Override view' app/views/workarea/storefront/products/show.html.haml
+```
+
+### Customize the File
+
+Now you can edit the file as necessary for your requirements. Be sure to edit the copy of the file within your application and not the original engine copy. For my example, I re-ordered the product description and recommendations, as shown in the diff below.
+
+```diff
+diff --git a/app/views/workarea/storefront/products/show.html.haml b/app/views/workarea/storefront/products/show.html.haml
+index 1ef4ec4..6969e5e 100644
+--- a/app/views/workarea/storefront/products/show.html.haml
++++ b/app/views/workarea/storefront/products/show.html.haml
+@@ -27,11 +27,6 @@
+       .product-details{ class: "product-details--#{@product.template}" }
+         = render "workarea/storefront/products/templates/#{@product.template}", product: @product
+
+- - if @product.description.present?
+- .product-detail-container__description#description
+- %h2.product-detail-container__description-heading= t('workarea.storefront.products.description')
+- .product-detail-container__description-body{ itemprop: 'description' }!= @product.description
+-
+       - if @product.recommendations.any?
+         %h2= t('workarea.storefront.recommendations.heading')
+
+@@ -41,6 +36,11 @@
+               .product-summary.product-summary--small{ itemprop: 'isRelatedTo', itemscope: true, itemtype: 'http://schema.org/Product' }
+                 = render 'workarea/storefront/products/summary', product: product
+
++ - if @product.description.present?
++ .product-detail-container__description#description
++ %h2.product-detail-container__description-heading= t('workarea.storefront.products.description')
++ .product-detail-container__description-body{ itemprop: 'description' }!= @product.description
++
+       %div{ data: { recommendations_placeholder: recent_views_path } }
+
+       = append_partials('storefront.product_show', product: @product)
+```
+
+Browsing to the same page demonstrates the final result: the recommendations display above the product description.
+
+![Storefront product page after overriding](images/storefront-product-after-overriding.png)
+
+## Override Generator
+
+Workarea also provides an override generator, which you can use to create overrides for a given type and path. Run the generator with the _‑‑help_ option to view its documentation. The following example demonstrates running the command in Workarea 3.1.2.
+
+```bash
+$ bin/rails g workarea:override --help
+Usage:
+  rails generate workarea:override TYPE PATH [options]
+
+Runtime options:
+  -f, [--force] # Overwrite files that already exist
+  -p, [--pretend], [--no-pretend] # Run but do not make any changes
+  -q, [--quiet], [--no-quiet] # Suppress status output
+  -s, [--skip], [--no-skip] # Skip files that already exist
+
+Options:
+  TYPE can be one of:
+    - views
+    - layouts
+    - stylesheets
+    - javascripts
+    - images
+    - fonts
+
+Description:
+  Generates application-specific overrides of Workarea front-end files
+
+Examples:
+  rails g workarea:override views workarea/storefront
+  rails g workarea:override layouts workarea/storefront/application.html.haml
+  rails g workarea:override layouts workarea/admin/application.html.haml
+  rails g workarea:override stylesheets workarea/storefront/reviews
+  rails g workarea:override stylesheets workarea/core/helpers/_respond_to.scss
+  rails g workarea:override javascripts workarea/core/modules/string.js
+  rails g workarea:override javascripts workarea/storefront/templates/btn.jst.ejs
+  rails g workarea:override fonts workarea/storefront/icons.woff
+  rails g workarea:override stylesheets jquery_ui/admin/_ui_dialog.scss
+```
+
+## Impact on Upgrades
+
+Overrides provide enormous design flexibility, but they can affect the cost of upgrading your application to a newer release of the platform. Because your overrides maintain no relationship to the files they've replaced in the platform, changes to the files introduced by the platform will not be present in your application after upgrading. You will need to manually apply the same changes to your overrides if desired.
+
+To mitigate this problem, Workarea provides [Workarea Upgrade](https://stash.tools.weblinc.com/projects/WL/repos/workarea-upgrade/browse). Among its features, it will show diffs of Workarea changes for the files you've overridden in your application, easing the process of merging those changes into your overrides.
+
+## Overrides within Plugins
+
+Unlike other [extension](extension-overview.html) techniques, overriding is used almost exclusively by applications and is used by plugins in only rare cases. Although plugins are technically able to override files, it becomes problematic when other plugins or the application in which they are installed also want to override the same files. Plugins therefore override files only when they can assume they are the canonical source for the files, such as a theme plugin overriding the Storefront layout and assets.
+
+## Notes
+
+[1] I'm using Unix tools in my examples because they're universally available and are easy to represent in textual documentation. You should use whatever tools you are comfortable with for searching and browsing source code.

data/docs/source/articles/overview.html.md

@@ -0,0 +1,43 @@
+---
+title: Overview
+excerpt: An overview of what Workarea is, how it's distributed, and its major technologies.
+---
+
+# Overview
+
+Workarea is an open-source, enterprise-grade commerce platform. The platform and many of its plugins are maintained by Workarea. The rest of the Workarea community maintain the majority of Workarea's plugins and also contribute directly to the platform. Workarea Commerce Cloud is a subscription service offered by the [Workarea](https://www.workarea.com) company, which includes extended functionality and cloud-based hosting.
+
+## Built with
+
+### Ruby
+
+Workarea is written in Ruby, and is built on the [Ruby on Rails](https://rubyonrails.org) framework. As such, it's distributed as a gem via [RubyGems](http://guides.rubygems.org/). Workarea and it's plugins are [Rails' engines](https://guides.rubyonrails.org/engines.html) that get mounted inside a host Rails application. Workarea also relies on [Sidekiq](https://sidekiq.org) for processing background work.
+
+### Databases
+
+#### MongoDB
+
+[MongoDB](https://www.mongodb.com) serves as the canonical, database-of-record in Workarea. Its flexible, document-oriented data model is a good fit for diverse catalogs offered by retailers and fits well with our plugin model, where the schema can be managed in the application code.
+
+#### Elasticsearch
+
+[Elasticsearch](https://www.elastic.co/products/elasticsearch) drives all the important listing and browsing done in Workarea. This includes storefront search, product recommendations, category browsing, admin indexes, and more. Its robust querying makes it a perfect fit for all the searching requirements a large ecommerce system has.
+
+#### Redis
+
+[Redis](https://redis.io) is Workarea's Swiss army knife of databases. It stores the Sidekiq job queue, provides storage for recommendations, serves as the Rails cache, and more.
+
+## Customization
+
+Workarea is designed to be customized to work for merchants with different needs. The four primary ways of customizing Workarea's behaviors are [configuration](configuration.html), [plugins](plugins-overview.html), [decoration](decoration.html), and Rails' overrides system ([overriding](overriding.html)).
+
+## Testing
+
+Workarea inherits the Rails' community's ethic of testing. In this spirit, Workarea distributes its test suite as runnable and customizable, just like any application code using decoration techniques. This helps implementers of Workarea to ensure their customizations don't break Workarea out-of-the-box functionality and helps with upgrades to new versions. [Read more on testing.](testing.html)
+
+## How do I get started?
+
+You have two options for jumping in with Workarea.
+
+1. Try out a user-facing demo, using [instructions from our README](https://github.com/workarea-commerce/workarea#demo)
+2. [Create a new app](create-a-new-app.html) and start coding

data/docs/source/articles/plugins-overview.html.md

@@ -0,0 +1,12 @@
+---
+title: Plugins Overview
+excerpt: A Workarea plugin is a Rails engine used to add to or customize the features of the Workarea platform. Plugins allow code to be managed and maintained separately by different teams, in different repositories, and on different schedules. Plugins distribu
+---
+
+# Plugins Overview
+
+A Workarea plugin is a Rails engine used to add to or customize the features of the Workarea platform. Plugins allow code to be managed and maintained separately by different teams, in different repositories, and on different schedules. Plugins distribute the development of the platform so the core developers don't have to develop every feature a project may require.
+
+Systems integrators (SIs) are encouraged to develop their own plugins to package features for re-use across projects or teams.
+
+

data/docs/source/articles/prerequisites-and-dependencies.html.md

@@ -0,0 +1,202 @@
+---
+title: Prerequisites & Dependencies
+excerpt: The Workarea platform stands on the shoulders of many other software projects. Workarea's training and support materials focus on Workarea software and do not teach the specifics of Workarea's dependencies. However, this "prerequisite" knowledge is covere
+---
+
+# Prerequisites & Dependencies
+
+The Workarea platform stands on the shoulders of many other software projects. Workarea's training and support materials focus on Workarea software and do not teach the specifics of Workarea's dependencies. However, this "prerequisite" knowledge is covered in depth by many other resources. In this guide, I introduce Workarea's most notable dependencies and provide links to resources that cover each.
+
+## Help from the Workarea Community
+
+While studying these topics, you may need to reach out for help. In addition to the usual places ([Google](https://www.google.com/), [Stack Overflow](http://stackoverflow.com/)), consider jumping on the [Workarea Slack](https://workarea-community.slack.com), where developers who have experience with Workarea applications will have the opportunity to help you.
+
+## Critical Paths
+
+For those looking for the short list(s), I've listed below the critical paths for back end and front end specialists.
+
+### Back End
+
+- [Ruby language](https://www.ruby-lang.org/en/) and [object oriented programming in Ruby](http://www.poodr.com/)
+- [Ruby on Rails web framework](http://rubyonrails.org/)
+- [Sidekiq background jobs](http://sidekiq.org/)
+- [MongoDB document database](https://www.mongodb.org/) and [Mongoid object-document mapper](https://docs.mongodb.org/ecosystem/tutorial/ruby-mongoid-tutorial/)
+- [Elasticsearch full text search engine](https://www.elastic.co/products/elasticsearch) and [Elasticsearch libraries for Rails applications](https://github.com/elastic/elasticsearch-rails/tree/master/elasticsearch-persistence)
+
+### Front End
+
+- [Ruby language](https://www.ruby-lang.org/en/)
+- [Ruby on Rails web framework](http://rubyonrails.org/)
+- [Haml templates](http://haml.info/)
+- [SCSS stylesheets](http://sass-lang.com/)
+- [BEM-based UI components](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/)
+- [lodash utility library](https://lodash.com/)
+- [jQuery DOM manipulation and ajax library](https://jquery.com/)
+
+Continue reading for a deeper dive into Workarea's dependencies.
+
+## Fundamentals
+
+Let's start with some fundamentals.
+
+### Operating System & Shell
+
+Although it may be possible to develop Workarea applications on Windows, Workarea is hosted on and designed for use on Unix operating systems (including macOS). The <dfn>shell</dfn> is the program that passes commands from your keyboard to the operating system, and is also known as the <dfn>command line interface</dfn>, or <dfn>CLI</dfn>, for the OS. Many Workarea features depend on familiarity with the shell.
+
+[The Command Line Crash Course](http://cli.learncodethehardway.org/book/) and [LinuxCommand.org](http://linuxcommand.org/) are online tutorials that present increasingly complex shell concepts while encouraging you to follow along. The material from LinuxCommand.org has also been developed into an ebook that's available [from the author](http://linuxcommand.org/tlcl.php) and [from No Starch Press](https://www.nostarch.com/tlcl.htm).
+
+### Git
+
+[Git](https://git-scm.com/) is the version control system used to manage Workarea source code and is the VCS you will most likely use to manage your application source code as well.
+
+If you're completely new to Git, try it out interactively with [Try Git](https://try.github.io/levels/1/challenges/1). The [project's website](https://git-scm.com/) provides full API documentation for the command line interface and provides information about [graphical applications](https://git-scm.com/downloads/guis) for working with Git.
+
+The site also provides downloads of the book [Pro Git](https://git-scm.com/book/en/v2), a easily digestible introduction to using Git. The book is also available [from Apress](http://www.apress.com/9781484200773).
+
+## Ruby & Rails
+
+Ruby and Rails are at the heart of Workarea, both technologically and philosophically. Both value developer happiness and productivity, two design principles that guide the development of the Workarea platform.
+
+### Ruby Language
+
+The predominant programming language in Workarea is [Ruby](https://www.ruby-lang.org/en/), a general purpose programming language used primarily for web applications due to the success of Ruby on Rails, which I cover below. While known chiefly as an object-oriented language, Ruby also provides strong support for the functional programming paradigm and is often used procedurally as a scripting language. Ruby's reader-friendly syntax, supportive community, and expansive standard library make it a favorite among developers.
+
+Those new to Ruby can learn it interactively at [Try Ruby](http://tryruby.org/levels/1/challenges/0). Beyond that, check out [Programming Ruby](https://pragprog.com/book/ruby4/programming-ruby-1-9-2-0), also known as <dfn>The Pickaxe</dfn>. The book was the seminal English language work on Ruby. It provides a complete tutorial and reference for the language and is updated regularly by its original author and publisher. For a more whimsical explanation of the language, check out the ebook [Why's (Poignant) Guide to Ruby](http://poignant.guide/), a community favorite. Or, if you're an experienced programmer coming from another language, you may want to consult O'Reilly's [The Ruby Programming Language](http://shop.oreilly.com/product/9780596516178.do), co-authored by Yukihiro Matsumoto (Matz), the creator of Ruby.
+
+Ruby's [official documentation](http://ruby-doc.org/) covers Ruby Core as well as the Standard Library, a collection of "blessed" libraries that ship with Ruby. The Ruby [project website](https://www.ruby-lang.org/en/) links to many other Ruby resources.
+
+I'd also like to note that the Rails web framework includes [Active Support Core Extensions](http://edgeguides.rubyonrails.org/active_support_core_extensions.html) which extend many of Ruby's classes with additional useful methods. Many of these methods are used heavily in Workarea.
+
+### Ruby Version Management
+
+Ruby version managers exist to (1) install ruby versions and (2) change ruby versions. You will likely need many versions of Ruby installed to work on multiple applications that were developed at different points in time.
+
+Workarea developers generally use [rbenv](https://github.com/rbenv/rbenv) + [ruby-build](https://github.com/rbenv/ruby-build) for this purpose. Other popular choices are [chruby](https://github.com/postmodern/chruby) + [ruby-install](https://github.com/postmodern/ruby-install) or [rvm](https://rvm.io/). Refer to each project's documentation to see how the tool installs and switches between different ruby versions.
+
+### Ruby Programming
+
+Ruby is often used for two different types of programming, scripting and applications. While scripts are typically written procedurally, applications tend to follow object-oriented design principles in order to manage complexity. For a primer on object-oriented design in Ruby, I highly recommend [Practical Object-Oriented Design in Ruby](http://www.poodr.com/), aka <dfn>POODR</dfn>. Sandi Metz leverages her decades of programming experience to bring object-orientation to life with clear examples using idomatic Ruby.
+
+Central to the long term maintenance of applications is <dfn>refactoring</dfn>, restructuring software without changing its observable behavior. [Refactoring: Ruby Edition](http://martinfowler.com/books/refactoringRubyEd.html) is a rewrite of Martin Fowler's classic text on refactoring, this time with code examples in Ruby.
+
+### Rails
+
+[Ruby on Rails](http://rubyonrails.org/) is the de facto standard web framework for Ruby. Rails' [design principles](http://rubyonrails.org/doctrine/) of developer happiness and productivity were inspired by Ruby. Workarea builds heavily on Rails, both technologically and philosophically.
+
+If you're new to Rails, get started with one of many Rails tutorials. The book [Agile Web Development with Rails](https://pragprog.com/book/rails4/agile-web-development-with-rails-4) is one such tutorial and was originally written by David Heinemeier Hansson (DHH), the creator of Rails. The book is now maintained by Sam Ruby under the same publisher and is diligently updated for each new version of Rails.
+
+Next move on to the [Ruby on Rails Guides](http://guides.rubyonrails.org/), which are maintened by the Rails team and community, and cover the different aspects of Rails in greater depth. Workarea tries to deviate as little as possible from Rails, but one difference is the use of Mongoid instead of Active Record. I explain Mongoid below, but mention it here because Active Record is covered prominently in the Rails guides. Fortunately, Mongoid copies the API of Active Record, so if you have an existing knowledge of Active Record, it will translate well to Mongoid.
+
+Finally, for a class and method level reference, refer to the [Rails API Documentation](http://api.rubyonrails.org/).
+
+### Testing
+
+Automated testing is core to the Ruby community and to Workarea. Workarea uses several testing tools, some of which are listed below.
+
+| Project | Description |
+| --- | --- |
+| [Minitest](https://github.com/seattlerb/minitest) | Testing framework for Ruby including test runner, assertion library, and mocking library |
+| [Capybara](https://github.com/jnicklas/capybara) | Acceptance testing library providing a DSL to drive a headless browser |
+| [WebMock](https://github.com/bblimke/webmock) | A library for stubbing and setting expectations on HTTP requests in Ruby |
+| [vcr](https://github.com/vcr/vcr) | Library for recording and replaying HTTP requests and responses |
+
+### Additional Dependencies
+
+The following table lists other notable libraries utilized by Workarea.
+
+| Project | Usage |
+| --- | --- |
+| [Sidekiq](https://github.com/mperham/sidekiq) | Process potentially expensive jobs in the background |
+| [Sidekiq-Cron](https://github.com/ondrejbartas/sidekiq-cron) | Schedule Sidekiq jobs |
+| [Dragonfly](https://markevans.github.io/dragonfly/) | Store files and process images using ImageMagick |
+| [Active Merchant](https://github.com/activemerchant/active_merchant) | Integrate with a variety of payment gateways |
+| [I18n.js](https://github.com/fnando/i18n-js) | Provide Ruby I18n translations in JavaScript |
+| [JsRoutes](https://github.com/railsware/js-routes) | Provide Rails named routes in JavaScript |
+| [Kaminari](https://github.com/amatsuda/kaminari) | Paginate collections |
+| [Local Time](https://github.com/basecamp/local_time) | Display times in a user's local time zone |
+| [Predictor](https://github.com/Pathgather/predictor) | Produce product recommendations |
+| [Rack::Attack!!!](https://github.com/kickstarter/rack-attack) | Block and throttle abusive requests |
+
+Ruby libraries for interacting with databases are covered below.
+
+## Databases
+
+Workarea applications depend on three different document-based (NoSQL) databases: MongoDB, Elasticsearch, and Redis. Each of the databases uses a client/server architecture, and Workarea provides a Ruby client for each database. Resources for the three databases and their Ruby drivers are provided below.
+
+### MongoDB & Mongoid
+
+[MongoDB](https://www.mongodb.org/) is used as the primary data store in Workarea applications. MongoDB is a NoSQL database designed for modern web applications. It is designed primarily for developers rather than analysts and employs an intuitive data model based on documents rather than tables. MongoDB utilizes a client/server architecture where programming language APIs are used to communicate with the server via BSON, a binary representation of JSON (with proprietary extensions).
+
+Workarea applications typically run on the latest version of the database, currently v3.2.
+
+While there is a low level Ruby driver for MongoDB, Workarea uses [Mongoid](https://docs.mongodb.org/ecosystem/tutorial/ruby-mongoid-tutorial/), an <dfn>Object-Document Mapper</dfn>, or <dfn>ODM</dfn>. Mongoid provides an API that is purposefully similar to [Active Record](http://guides.rubyonrails.org/active_record_basics.html), the library used to persist models in Rails applictions using relational databases. If you have any familiarity with Active Record, that knowledge should transfer directly to Mongoid.
+
+If you're new to MongoDB, I recommend the book [MongoDB in Action, Second Edition](https://www.manning.com/books/mongodb-in-action-second-edition), written by a former employee of [MongoDB, Inc.](https://www.mongodb.com/), the corporate sponsor and developer of MongoDB. The book introduces Mongo and compares it to other databases before explaining how to develop a Mongo application using the MongoDB shell and MongoDB Ruby driver. The second edition was updated to cover MongoDB version 3.0.
+
+MongoDB Inc. also provides free online courses at [MongoDB University](https://university.mongodb.com/). While they don't teach a Ruby-specific course, all the Mongo drivers have a similar API, so knowledge of one will transfer to any other.
+
+The following learning resources are available directly from MongoDB:
+
+- [MongoDB Manual](https://docs.mongodb.org/manual/)
+- [Getting Started Guide](https://docs.mongodb.org/getting-started/shell/)
+- [Ruby Driver Tutorial](https://docs.mongodb.org/ecosystem/drivers/ruby/)
+- [Mongoid Tutorial](https://docs.mongodb.org/ecosystem/tutorial/ruby-mongoid-tutorial/)
+
+Workarea also uses the following libraries to extend Mongoid:
+
+| Project | Extension to Mongoid |
+| --- | --- |
+| [Money-Rails](https://github.com/RubyMoney/money-rails) | `Money` data type |
+| [Mongoid::ActiveMerchant](https://github.com/bencrouse/mongoid-active_merchant) | `ActiveMerchant::Billing::Response` data type |
+| [Mongoid::AuditLog](https://github.com/bencrouse/mongoid-audit_log) | Audit logging of Mongoid documents |
+| [mongoid-paranoia](https://github.com/haihappen/mongoid-paranoia) | "Soft" deletion of Mongoid documents |
+| [mongoid-tree](https://github.com/benedikt/mongoid-tree) | Tree structure |
+
+### Elasticsearch
+
+[Elasticsearch](https://www.elastic.co/products/elasticsearch) is the full text search engine for Workarea applications. The project is built on top of Apache Lucene, a full text search engine library used to integrate search functionality into Java applications. Elasticsearch, also written in Java, hides the complexities of Lucene behind RESTful APIs. Elasticsearch clients use these APIs to communicate with Elasticsearch servers via JSON over HTTP.
+
+Workarea uses Elasticsearch version 5.x. Workarea applications use a Ruby client to communicate with the Elasticsearch server.
+
+If you're new to Elasticsearch there is no better resource than [Elasticsearch: The Definitive Guide](https://www.elastic.co/guide/en/elasticsearch/guide/current/index.html). This holistic and accessible book presents the technology and philosophy of Elasticsearch and is written and maintained by two trainers from [Elastic](https://www.elastic.co/), the corporate sponsor and developer of Elasticsearch. The book is also available from [O'Reilly Media](http://shop.oreilly.com/product/0636920028505.do).
+
+Elastic also provides [in person trainings](https://www.elastic.co/training) at various locations for a fee.
+
+The [Elasticsearch Reference (v5.0)](https://www.elastic.co/guide/en/elasticsearch/reference/5.0/index.html) is a complete reference to the Elasticsearch RESTful APIs.
+
+### Redis
+
+Workarea also makes use of [Redis](http://redis.io/), an in-memory data structure store, used as a database and cache. Workarea applications use the [Ruby client library for Redis](https://github.com/redis/redis-rb) to communicate with a Redis server over the network via a proprietary protocol.
+
+Due to its simplicity, there is little to learn about Redis. Refer to the [command reference](http://redis.io/commands) as needed to manipulate keys and values stored in Redis.
+
+## Front End
+
+### HTML & CSS
+
+Workarea uses a modular component library to compose its UIs. Front end developers will benefit from familiarity with a UI component library, such as [Bootstrap](http://getbootstrap.com/components/). Workarea uses [style guides](style-guides.html) to document and unit test its UI components. Unit testing of front end components is not a well adopted practice among front end developers. If this concept is new to you, review the [test suite for Normalize.css](https://github.com/necolas/normalize.css/blob/master/test.html) ([view the rendered HTML](http://htmlpreview.github.io/?https://github.com/necolas/normalize.css/blob/master/test.html)), which demonstrates the idea well.
+
+Another important concept of the Workarea front end is [BEM](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/), which stands for <dfn>Block, Element, Modifier</dfn>. Workarea uses the BEM methodology for naming and structuring HTML and CSS. BEM and other concepts are explained in [CSS Guidelines](http://cssguidelin.es/), which Workarea follows as a style guide.
+
+Front end developers should also familiarize themselves with the following HTML/CSS dependencies:
+
+| Project | Description |
+| --- | --- |
+| [Haml](http://haml.info/) | The server-side templating language responsible for rendering HTML |
+| [Sass (SCSS)](http://sass-lang.com/) | The stylesheet language used to produce CSS |
+| [Normalize.css](https://necolas.github.io/normalize.css/) | A library to normalize CSS across browsers (similar to a CSS reset), version 3.x |
+
+### JavaScript
+
+Workarea depends on a variety of JavaScript libraries, most notably the following:
+
+| Project | Description |
+| --- | --- |
+| [lodash](https://lodash.com/) | JavaScript's missing standard library which provides cross-browser implementations of `map`, `reduce`, and similar functions, version 3.x |
+| [jQuery](https://jquery.com/) | The de facto standard libarary for DOM manipulations and ajax, version 1.11.x |
+| [jQuery&nbsp;UI](https://jqueryui.com/) | Extensible UI widget library, version 1.11.x |
+| [jQuery&nbsp;Validation&nbsp;Plugin](http://jqueryvalidation.org/) | Library for client-side validation |
+| [Feature.js](http://featurejs.com/) | Feature detection library, version 1.0.1 |
+| [Teaspoon](https://github.com/modeset/teaspoon) | JavaScript test runner for Rails applications |
+| [Mocha](https://mochajs.org/) | JavaScript testing framework |
+| [Chai](http://chaijs.com/) | JavaScript assertion library |