# Application structure

This section is critical to understanding the way that your application should be organised in order to have a seamless development experience with BladeRunnerJS, while at the same time achieving a modular application structure.

## Apps

Apps consist of a number of _bladesets_ and _aspects_. They conform to the _Java Enterprise Edition 5_ specification of a web-app, so you’re free to add your own servlets and filters to the WEB-INF/lib directory, and update the web.xml file appropriately. The servlets and filters that comprise the BladeRunnerJS server infrastructure are populated when an App is created.

Other JavaScript libraries can be added into the _thirdparty-libraries_ directory. You can also create your own _[user libraries](bladerunnerjs-user-libraries.md)_ and add them to the _libs_ directory. They will all be included into the JavaScript bundle file if they are referenced in your code.

BladeRunnerJS apps are delivered as _J2EE WAR_ files. The specific settings for each environment are configured via _JNDI_. You can specify a database connection or even an environmental string to be used, in HTML. BladeRunnerJS filters replace known tokens with the value of your JNDI configured variable.

![br_apps_dir_2](../../../images/br_apps_dir_2.png)

## Aspects

Typically, different Aspects will use different layout managers. A fully-fledged desktop browser aspect for example, might use a complex layout manager like [_Webcentric_](../webcentric/index.md), with a mouse-oriented display, and many components and panels in view at the same time. Another aspect might use HTML, and embed single components for use on a mobile device. Aspects allow you to share blades between different web pages.

Users will request the entry page of the aspect (usually _index.html_) from the root of the aspect’s directory. The various bundlers scan the entry page, perform their dependency analysis and generate the appropriate bundles. Only the referenced blades are loaded, and blades from different bladesets may be included. Any assets common to the whole aspect are loaded from the _src_, _test_ and _resources_ directories of the aspect.

If you wish to create code (or use libraries) that are not compatible with the Caplin bundlers, simply place that code and other assets inside the _unbundled-resources_ folder.

![br_aspect_dir](../../../images/br_aspect_dir.png)

## Bladesets

A bladeset is a collection of blades that share some common code. They can also share assets such as styles, HTML templates and images. This allows you to create logical groupings of blades that display information in a consistent way. For instance: you would use a bladeset to share the custom code for numerical formatting in a set of blades, or to house a common date-chooser configuration.

![br_bladeset_dir](../../../images/br_bladeset_dir.png)

## Blades

Each blade is a separate module, containing the code and resources for a single feature. For example: a form component, which receives, validates and submits data to the server. Largely, it consists of various JavaScript classes that contain business and presentation logic, plus some CSS and HTML that provide the view. It contains all the assets required to:

1. Run the feature in a containing App.
2. Run the feature in a stand-alone web-page known as a workbench.
3. Test any code that is part of the blade (unit and acceptance tests).

Blades can reference code in libraries, but _cannot_ directly reference code in other blades. This isolation means blades can be moved, deleted, copied and changed without affecting other blades. All the assets are held under a single directory that conforms to the structure shown below, with any assets that are shared between blades being held at the bladeset level.

![br_blade_dir](../../../images/br_blade_dir.png)

**📌 NOTE**\
A _themes_ directory at any level can contain a _common_ directory for images and CSS which are common to any theme selected (such as structural CSS). The contents of this directory are always included in the application.

You supply common services to your blade via our service registry. Blades communicate with each other indirectly via the event hub.

All code must reside under the correct sub-directory e.g. all JavaScript code must be placed inside the src directory. Most of your app’s code consists of a (possibly large) number of blades. The code from those blades is automatically combined by the bundlers and returned to the browser.