Ushahidi Platform: Under the Hood (Part 3)

This post is the third in a series of articles that will be devoted to explaining the Ushahidi Platform at a technical level for programmers and deployers. As we saw in the first blog post, Ushahidi Platform is radically changing under the hood, pivoting towards a very strictly defined architecture that enables all of the business logic of the platform to be independently tested, free of details such as the database or the web, which is nothing more than delivery mechanism. But of course, the details are important too, even if they are layers away from the core business logic. The root of delivery in the Ushahidi Platform is a REST API, not the web interface that most people interact with. By building the API first, we have ensured that multiple interfaces are possible. Ushahidi Platform includes a mobile-first web client, but I expect that very specific mobile apps will be developed to support specific deployments as the platform matures. We are leveraging many open source projects to build the web client that comes with Ushahidi Platform. The initial prototype of the web app, which is still in use today, was built using Backbone, Marionette, and Foundation, as well as many other smaller libraries. Of course, as in all projects, the choice of technology has come into question with time. As the application has grown and new people are added to the team, we have found that Backbone + Marionette requires too much boilerplate, which results in a lot of copy/pasting forking and frustration for the team. To add to the frustration, we have been unable to use Foundation widgets as intended, because the Javascript was not designed to operate with a single-page application. (To the credit of Zurb, they are addressing this in the near future with Foundation for Apps, but it won’t be soon enough for us to use it.) Taking these concerns into account, along with upcoming design changes, we decided to rebuild the web client completely using an entirely new stack based on Bourbon (with Neat, Bitters, and Refills). Seth has written Introducing the Ushahidi Platform Front-End Stack to explain the various pieces that make up the new client. But Bourbon is only a replacement for Foundation, not for Backbone or Marionette, so we spent about a month evaluating the differences between Ember, Mithril, and Angular. Although all have the same general purpose, each has specific pros and cons for our usage. There are already a couple of projects at Ushahidi that are using Ember, which would have been helpful for sharing resources and experiences. We liked the feel of the syntax and the extensive documentation. It also has some nice features that would make it easier to build localization and internationalization. But ultimately, we decided that Ember didn’t really address the issues we saw with using Handlebar templates and duplicating the MVC pattern in the front end. Next up was my personal favorite choice of Mithril, which is relatively new and very bare bones framework. This framework has absolutely fantastic documentation, and the author obviously has deep experience with Angular, which he uses to create something faster and better. Reading his blog feels like a challenge to write better code, which is always a positive thing. But because Mithril is so minimal and so new, the community and ecosystem of tools are both quite small. We were also not entirely happy with Mithril’s functional templates. Finally, we have Angular, which is well established and comes from Google. We really like the idea of using HTML as the templating language, because it is well understood and allows our design team to prototype quickly. The large ecosystem of plugins and tutorials, which is reflective of the much larger community, is also a big benefit for us. The biggest downside to Angular seems to be potential performance issues due to “dirty checking” in $scope, which everyone seems to agree is an implementation problem rather than a fundamental issue in Angular. As much as we liked Mithril and Ember, Angular was a clear winner when we considered the availability of documentation, variety of plugins, and large community. So what will all of this end up looking like when you actually deploy the platform? There will be two separate web servers: one that runs a PHP server for the backend API, and one that serves a totally static web client built with Bourbon and Angular. The web client will authenticate with the backend using OAuth and present the user interface based on the role of the user. We think this configuration will offer the best flexibility and most consistent performance possible. If you have any feedback on using any of the tools that were talked about in this blog post, please leave a comment below or message me on Twitter @shadowhand, I’d love to hear any insights or questions you have. I hope that this post gives you a taste of where the Ushahidi Platform web client is headed and what skills you will need to work on it. The next article in this series will show how to interact with the API using a Javascript and AJAX calls. Want to get involved? We can use help with some wishlist features and with general bug reporting. Please read the developer guide wiki page for more information on our current community opportunities and have a look at our workboard on Phabricator. If you just want to chat about the platform or architecture, Woody is often available via IRC, in the #ushahidi and #cleancode channels on irc.freenode.net.