JS Architecture

JS Framework

The Framework driving the user agent is Flight, which is "a lightweight, component-based JavaScript framework that maps behavior to DOM nodes". Flight is in itself pretty lightweight in the sense that it isn't very opinionated, except for separation of concerns:

Flight enforces strict separation of concerns. When you create a component you don't get a handle to it. Consequently, components cannot be referenced by other components and cannot become properties of the global object tree. This is by design. Components do not engage each other directly; instead, they broadcast their actions as events which are subscribed to by other components.

It only uses DOM Events to communicate among components. The justification for that, the separation of concerns is pretty debatable, because you have the very same dependencies, only that you convert compile-time dependencies into runtime-dependencies, so that claim can be easily dismissed. Instead, it seems to be a rather cheap workaround for the lacking dependency injection.

However, Flight has been deprecated. Due to this change, new components have been developed with ReactJS, which is also a component-driven library, thought it makes use of a virtual DOM to deal with renderization.

Though we have begun all new development with React, the Inbox is still entirely in FlightJS.

Code structure - Inbox

The code is mostly structured along

• Features (separated into Data Access Objects and UI)
• Dispatchers (bootstrapping UI initialization)
• Mixins (containing shared functionality used among different components)
• Sandbox scripts (loaded in the iFrame sandbox)
• Monkey Patches

You can check this part of the code here.

The JS is authored using AMD, which is being concatenated, compiled and minified at build time.

Testing is done w/ Jasmine as test runner and matcher framework. The test structure is similar to the code.

Code structure - Login and Account Recovery Pages

Here, the code structure follows that of components. Every major component has its own folder with the respective CSS, JS, and test. We put this part of the code in a separated folder for reasons of organization.

This part of the JS code makes use of CommonJS, so it's both compatible with Node and the browser. We use Webpack for bundling and minifying.

CommonJS and ReactJS allow us to be browser independent, so we chose to run our tests with Mocha and ExpectJS. All component tests are kept inside the code structure, with their respective components. Only integration tests are treated separately.

Packaging and running tests

All necessary JS tasks are kept in web-ui/package.json for easy access. In short, both the FlightJS and ReactJS sections have their own compilation and testing requirements, with their respective scripts for running them. You should find everything you need in the package.json.

These can also be run from outside the web-ui folder with make. Check out the scripts for these in the Makefile or check the Tests documentation.