Merge pull request #1187 from benthomasson/networking-acceptance-ben

Adds acceptance doc for networking UI
2026-01-15 20:00:43 -03:30 · 2018-04-05 09:07:57 -04:00 · 2018-04-05 09:07:57 -04:00 · dfe35bd405
commit dfe35bd405
parent ab277e816a 92dc450940
48 changed files with 2334 additions and 0 deletions
--- a/docs/img/network-example-1.png
+++ b/docs/img/network-example-1.png
--- a/docs/img/network-example-2.png
+++ b/docs/img/network-example-2.png
--- a/docs/networking.feature
+++ b/docs/networking.feature
@ -0,0 +1,76 @@
+Feature: Networking Topology Visualization
+    In order to increase the ease and understanding of network automation
+    As as network engineer
+    I want a visualization of the network topology so that I can
+    easily understand how the network topology is connected
+
+    Scenario: Blank canvas
+        Given an ansible inventory
+        When the user clicks on the network topology icon for that inventory
+        Then populate the toolbox with the data loaded from inventory
+
+    Scenario: Device Organization
+        Given an ansible inventory loaded into the canvas toolbox
+        When the user clicks and drags on a device in the inventory toolbox
+        Then place the device onto the topology canvas at the location of the user's mouse pointer
+
+    Scenario: Link Connection
+        Given an ansible inventory loaded into the canvas toolbox
+        When the user clicks and drags on a device in the inventory toolbox
+        Then automatically draw lines and circles that represent the links
+        And interfaces of the connected devices.
+
+    Scenario: Customize Layout
+        Given a canvas populated with a network topology
+        When the user clicks and drags on a device on the topology canvas
+        Then move the device to the location of the user's mouse pointer
+        And update the links and interfaces representations
+
+    Scenario: Export SVG
+        Given a canvas populated with a network topology
+        When the user clicks on the Export SVG button
+        Then capture the current view of the canvas
+        And download an SVG file of the canvas to the users computer
+
+    Scenario: Export YAML
+        Given a canvas populated with a network topology
+        When the user clicks on the Export YAML button
+        Then capture the state of the current view of the canvas
+        And download a YAML file that represents the data to the user's computer
+
+    Scenario: Pan
+        Given a canvas populated with a network topology
+        When the user clicks and drags on the background
+        Then move the viewport of the virtual canvas to match the user's mouse movement
+
+    Scenario: Zoom
+        Given a canvas populated with a network topology
+        When the user scrolls their mousewheel or clicks and drags on the zoom widget
+        Then scale the viewport of the virtual canvas to the zoom level reflected on the zoom widget
+
+    Scenario: Hide information when zooming out
+        Given a canvas populated with a network topology
+        When the user zooms out via mouse wheel or zoom widget
+        Then hide low-level information to provide a high-level overview as the zoom level changes
+
+    Scenario: Show more information when zooming in
+        Given a canvas populated with a network topology
+        When the user zooms in via mouse wheel or zoom widget
+        Then show more low-level information to provide more detail for the devices that are in view on the virtual canvas
+
+    Scenario: Device Detail
+        Given a canvas populated with a network topology
+        When the user clicks on show details device context menu button
+        Then show the device details including name, description, and host vars
+
+    Scenario: Remove Device
+        Given a canvas populated with a network topology
+        When the user clicks on remove device context menu button
+        Then remove the device and connected links from the canvas
+        And return the device to the inventory toolbox
+
+    Scenario: Search by Device Name
+        Given a canvas populated with a network topology
+        When the user types the device name or selects it from a device drop down list
+        Then position the viewport on the virtual canvas over the device with that name
+
--- a/docs/networking.md
+++ b/docs/networking.md
@ -0,0 +1,686 @@
+# Tower Networking Overview
+The networking tool is built with the main goal of allowing users to organize hosts and their relationships in a visual tool. Upon organizing hosts, the user can export these relationships as a YAML file and use that as input to a playbook.
+
+## Usage Manual
+
+### Inventory Creation
+The first step in is to create an inventory to be loaded into the network UI. There are no specific credentials or variables necessary to indicate that an inventory can be used in the network UI. The canvas can be used to represent any kind of inventory.
+
+### Network Node Creation
+Once the user has created an inventory, the next step is to add hosts to the inventory. This can be done manually or via an inventory source. Regardless of the import method, the host should be configured with a certain set of host varialbes that the network UI will reference when creating visual representations of the nodes. When creating a node that will be used in the network UI, the host variables follow this format:
+#### YAML:
+```
+ansible_topology:
+  type: host
+```
+#### JSON:
+```
+{
+ "ansible_topology": {
+  "type": "host",
+ }
+}
+```
+
+This structure denotes that the `type` that the network UI will use when drawing the visual representation of this node in the UI. The options for `ansible_topology` are as follows:
+
+| Key Name               | Value Type                                                  | Description                                                                                                                                                                   |
+|------------------------|-------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `type`                 | `str`                                                       | This will dictate what type of device the network UI will draw. Options are `host`, `switch`, and `router`. If left blank, the UI will denote the node type as `unknown`.     |
+| `links`                | `array`                                                     | This array contains objects that will denote what other nodes this particular node is connected to. Each connecting node object requires a `remote_device_name`, a `name`, and a `remote_interface_name`.
+
+Ex: suppose an inventory had three nodes, titled `host-00`, `switch-00`, and `router-00`. To connect `host-00` to the other two hosts, these would be the host variables saved to the host:
+```
+{
+ "ansible_topology": {
+  "type": "host",
+  "links": [
+   {
+    "remote_device_name": "router-00",
+    "name": "eth0",
+    "remote_interface_name": "eth0"
+   },
+   {
+    "remote_device_name": "switch-00",
+    "name": "eth1",
+    "remote_interface_name": "eth1"
+   }
+  ]
+ }
+}
+
+```
+Connecting the other two devices to each other, and you would get the following representation in the network UI:
+![Example 1](./img/network-example-1.png?raw=true)
+
+
+### Graphical UI and Restrictions
+Once the user has setup their inventory and nodes, they are ready to begin organizing their nodes using the graphical interface. The interface consists of an SVG canvas overlayed with panels that allow the user to drag nodes onto the canvas, as well as the ability to drill-down into the details of the items on the canvas. Below is a breakdown of the panels and their purpose on the interface:
+![Example 2](./img/network-example-2.png?raw=true)
+1. Toolbox: This panel on the left hand side of the screen will contain all the hosts that are included in the inventory. These are returned from `'/api/v2/inventories/:inventory_id/hosts/'` and therefore are returned in a paginated list. Because of this, the UI will make recursive calls to retrieve the list of hosts. This panel is collapsible using the wrench icon in the toolbar. This panel will scroll vertically with the list of devices.
+2. Canvas: The canvas takes up the full screen width and height. The canvas is where the user can drag and drop devices from the toolbox. Once a device is placed on the canvas, it is removed from the toolbox and it can interact with other devices on the canvas. If a device is removed from the canvas, it is not removed from the inventory, it is simply removed from the canvas, and will return to the toolbox
+3. Context Menu: When a user clicks on a device for the first time, it selects the device. A second click will activate a context menu with actions for the user. If the user has edit permission on the inventory, they will have the options to view the details of the device, or to remove the device. If the user does not have edit permission, they will only have the option to view the details of the device.
+4. Details: The right hand panel displays a read-only form for the device that is currently being inspected by the user. This panel is not shown by default, and is only shown after the user clicks the "Details" button on the context menu for a device. If mutiple devices are displayed on the canvas, the user can select different devices. As the user selects devices, the device detail panel on the right hand side will update with the host data.
+5.  Search: The search dropdown is a type-ahead dropdown that has a list of the devices currently on the canvas. It is organized by device type. It should always be in sync with the list of devices on the canvas. Devices on the toolbox will not show up in the search dropdown. Selecting a device from this dropdown will focus the canvas on the device.
+6. Toolbar actions: These are actions that are specific to the usability of the network UI. Currently they include the toggle for the toolbox, as well as a cheat sheet of hotkeys that can be used for shortcuts on the network UI.
+7. Actions dropdown: These are actions for the content of the network UI. These include "Export YAML" and "Export SVG" which is how a user could export the relationships on the canvas to download for their own use.
+8. Zoom Widget: The zoom widget ranges from 0-200%, and controls the zoom of the canvas. The user can also control the zoom using the scroll on their mouse or tracking pad. In future versions of this UI, the zoom will control what level detail they are able to see. But currently the only mode available is for devices in an inventory.
+
+
+## Verification
+
+See [networking.feature](networking.feature) for behavior scenarios.
+
+
+## Implementation Details
+
+**Introduction**
+
+The Networking UI component of AWX works differently from the rest of the AWX
+web UI to support high-scale interactive graphical design of networking
+topologies.
+
+The Networking UI is a virtual graphical canvas where graphical elements are
+drawn upon.  This canvas supports panning (scrolling horizontally and
+vertically) and scaling (zooming in and out), dynamic changing of modes, and
+other features that would be very difficult or impossible to implement with
+standard HTML events and rendering.
+
+This interface is more like computer graphics than it is building a styled text
+document with interactive components.  A good grasp of Cartesian coordinates,
+trigonometry, and analytic geometry are useful when working with this code.
+
+* See: <https://en.wikipedia.org/wiki/Analytic_geometry>
+
+**Design choices**
+
+Certain design choices were made to make the UI performant and scale to a large
+number of nodes in a diagram.  These include the use of simple ES5 functions for
+better performance over more advanced functions.  For instance C-style for-loops
+were many times faster than implementations of `forEach` or iterators which make
+function calls during each iteration.  This basic ES5 style should be followed
+throughout the implementation of the Network UI.
+
+**AngularJS**
+
+The Networking UI component uses AngularJS 1.6.x for part of the rendering pipeline
+but it is not a normal AngularJS web application.  AngularJS makes use of
+data-binding and watchers which I found do not scale to the number of elements
+we are trying to support in the Networking UI.   The Networking UI only uses
+AngularJS for SVG rendering (using AngularJS templates) which does scale
+sufficiently.
+
+
+**AngularJS Controllers**
+
+Instead of creating many AngularJS controllers and directives the networking UI
+uses one big controller to hold the state of the entire UI.  Normally this is
+an anti-pattern in AngularJS.  Here is was necessary to scale to a large number
+of on-screen elements.
+
+**AngularJS Directives**
+
+* See: <https://docs.angularjs.org/guide/directive>
+
+AngularJS directives are used in the networking UI application using the element
+matching style and the `templateUrl` option to include a template. A majority of
+the directives are defined in `network.ui.app.js`.
+
+* See: [network.ui.app.js](../awx/ui/client/src/network-ui/network.ui.app.js)
+```
+    .directive('awxNetLink', link.link)
+```
+
+* See: [link.directive.js](../awx/ui/client/src/network-ui/link.directive.js)
+```
+const templateUrl = require('~network-ui/link.partial.svg');
+
+function link () {
+  return { restrict: 'A', templateUrl};
+}
+exports.link = link;
+```
+
+**AngularJS Templates**
+
+* See: <https://docs.angularjs.org/guide/templates>
+
+Normal AngularJS templates are used with the networking UI controller.  
+The templates can be found in `/widgets`. Child
+scopes are created for sub-templates using the `ng-repeat` directive.
+
+In this example the `awx-net-link` directive expects a Link model to be
+passed to it.  The Link model is defined in the `models.js` file.
+
+* See: [link.directive.js](../awx/ui/client/src/network-ui/link.directive.js)
+* See: [link.partial.svg](../awx/ui/client/src/network-ui/link.partial.svg)
+
+* See: [network_ui.partial.svg](../awx/ui/client/src/network-ui/network_ui.partial.svg)
+```
+    <g ng-repeat="link in links">
+    <g awx-net-link></g>
+    </g>
+```
+
+* See: [models.js](../awx/ui/client/src/network-ui/models.js)
+```
+function Link(id, from_device, to_device, from_interface, to_interface) {
+    this.id = id;
+    this.from_device = from_device;
+    this.to_device = to_device;
+    this.from_interface = from_interface;
+    this.to_interface = to_interface;
+    this.selected = false;
+    this.remote_selected = false;
+    this.status = null;
+    this.edit_label = false;
+    this.name = "";
+}
+```
+ 
+The following example sets the toolbox.selected_item value to the variable 
+item which the directives used in the child scope expect to be set.
+
+* See: [inventory_toolbox.html](../awx/ui/client/src/network-ui/inventory_toolbox.partial.svg)
+```
+<g ng-repeat="item in [toolbox.selected_item]">
+```
+
+
+**DOM (Document Object Model)**
+
+No state is stored in or attached to the DOM.  All state is stored in
+javascript objects attached to the network ui controller.
+
+Direct DOM manipulation should not be used in the network UI unless absolutely
+necessary. JQuery should not be used.  The DOM is generated through the use of
+AngularJS templates.
+
+**SVG (Scalable Vector Graphics)**
+
+* See: <https://developer.mozilla.org/en-US/docs/Web/SVG>
+
+The network UI is built as one large SVG element (the SVG canvas) with other
+graphical elements (lines, circles, rectangles, paths, and text) absolutely
+positioned within the outer most SVG element.  The browser is not involved with
+layout of the elements within the SVG.   Each "widget" in the network UI needs
+to track or calculate its own position on the SVG canvas. The z-level of the
+elements are determined by the draw order on the canvas which is defined
+in `network_ui.partial.svg`.  Elements drawn first will be hidden behind
+elements drawn later.
+
+
+
+**Rendering Pipeline**
+
+Event -> Javscript objects -> AngularJS templates -> SVG
+
+AngularJS is used to render the SVG inside the SVG canvas using directives
+and templates.  AngularJS is also used to schedule when the SVG canvas will
+be updated. When an input event comes from the user, or an event is received
+over the websocket, javascript objects will be updated according the the network
+UI code.  Then AngularJS will be notified that it needs to update the templates
+either automatically for some events or explicitly using `$scope.$apply();` if
+not handled automatically by AngularJS.  The templates will render to SVG and be
+included in the DOM for the rest of the AWX UI.
+
+Because the networking UI does not use watchers nor data-binding features of
+AngularJS events flow in one way from event to javascript to angular to SVG.
+Events do not flow backwards through this pipeline.
+
+Clicking on an SVG element will not send the event to that SVG element directly
+from the browser.   It must be routed through the network UI code first.
+
+
+**SVG Primer**
+
+SVG uses tags to define graphical elements just like HTML uses tags to define
+text documents.   Commonly use tags include g, circle, rect, path, and text.
+SVG elements are absolutely positioned within an SVG canvas.  The group tag, g,
+is similar to the div tag in HTML.  Text in SVG must be contained in the text
+tag and cannot be outside tags as in HTML.
+
+* See: <https://developer.mozilla.org/en-US/docs/Web/SVG/Element>
+
+Each tag that describes a visual element requires X and Y coordinates as input
+to position that element. These coordinates are relative to position of the SVG
+canvas. The network UI uses the entire page height and width for the SVG canvas
+so that the position on the SVG on the canvas is the same as the position on
+the page.
+
+
+SVG supports graphical transformations on several tags to allow relative
+positioning of sub-elements which makes calculating the X and Y positions
+easier.   The network UI uses transformations often for this purpose.
+Transformations that are often used here are the translate, scale, and rotate
+transforms.  Translate moves the origin of the coordinate system to a new point
+for the sub-elements.  Scale multiplies the size of the units in a coordinate
+system by some factor.  Rotate performs a rotation about the origin by some
+number of degrees.  These functions are converted to a matrix operation on the
+coordinate system which can be efficiently applied.  It is often useful to use
+the transforms to simplify the calculations of X and Y coordinates instead of
+calculating those values in Javascript. Also these transforms make developing
+widgets much easier since we only need to keep up with a single point for the
+widget and all other points can be relatively positioned from that point.
+Hard-coding positions in widget development is the normal case since transforms
+can change the size and position of the widget when the widget is applied to
+the canvas.  Only when necessary should we calculate positions of parts of a
+widget in javascript.
+
+* See: <https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/transform>
+
+
+SVG paths are a mini-language for defining graphics operations in one tag. It
+is often used to create shapes that are more complex than lines, rectangles,
+and circles.  It is very useful for defining arcs.
+
+* See: <https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths>
+
+**SVG and CSS**
+
+CSS and SVG work really nicely together for setting style, colors, and fonts in SVG.
+The SVG uses different attributes for setting colors than does HTML elements.
+Most SVG elements use `stroke` and `fill` to define the colors and `stroke-width`
+to define the width of lines and curves. The attributes `font-family` and `font-size`
+are used to set the font for text elements in SVG.  The network UI uses the Less
+CSS compiler and BEM naming conventions to simplify and organize CSS.
+
+* See: [style.less](../awx/ui/client/src/network-ui/style.less)
+* See: <http://lesscss.org/>
+* See: <http://getbem.com/introduction/>
+
+**Events**
+
+All mouse and keyboard events are captured by the outer most element of the
+network UI.  Mouse movements, mouse clicks, and key presses are all routed by
+the network UI code and not by the browser.  This is done to implement
+interactions with the virtual graphical canvas that are not supported by the
+browser.  "Simple" things like buttons and text fields have to be handled by
+the network UI code instead of relying on the browser to route the mouse click
+to the appropriate object.
+
+
+The following code captures all the mouse movements, mouse clicks, mouse wheel,
+and touch events and sends them to the corresponding network UI controller functions.
+
+* See: [network_ui.partial.svg](../awx/ui/client/src/network-ui/network_ui.partial.svg#L3)
+
+```
+    <svg id="frame" class="NetworkUI"
+         ng-attr-height="{{graph.height}}"
+         ng-attr-width="{{graph.width}}"
+         ng-mousedown="onMouseDown($event)"
+         ng-mouseup="onMouseUp($event)"
+         ng-mouseenter="onMouseEnter($event)"
+         ng-mouseleave="onMouseLeave($event)"
+         ng-mousemove="onMouseMove($event)"
+         ng-mouseover="onMouseOver($event)"
+         ng-touchstart="onTouchStart($event)"
+         ng-touchmove="onTouchMove($event)"
+         ng-touchend="onTouchEnd($event)"
+         ng-tap="onTap($event)"
+         msd-wheel="onMouseWheel($event, $delta, $deltaX, $deltaY)">
+```
+
+
+Key events are captured by the following code:
+
+* See: [network.ui.controller.js](../awx/ui/client/src/network-ui/network.ui.controller.js)
+
+```
+    $document.bind("keydown", $scope.onKeyDown);
+```
+
+**Event Processing**
+
+This code works as an event processing pipeline where the source of the events
+may be mouse clicks, keystrokes, or messages from the server over the
+websocket.  This allows the appropriate processor to handle each event in turn
+or delegate the message to another processor.
+
+The following diagram documents the pipeline processors that handle the events.
+Events are injected into to the pipeline at `Start` and travel through the
+pipeline along the arrows. Events may be handled at a node in the pipeline,
+passed along to the next node, discarded, or transformed into another message
+and sent along the pipeline.  For instance `hotkeys_fsm` generates new and
+different type of events based on key presses that are injected at the
+beginning of the pipeline.
+
+![Event Pipeline](networking/pipeline.png)
+
+
+**Describing Behavior with Finite State Machines**
+
+To implement complex UI interactions predictably and correctly is a tough
+problem.  Often the problem is solved by creating a large library of generic
+reusable components that are rigorously tested and hardened by a large group of
+developers over a period of several years. Eventually the myriad bugs are
+hammered out at great expense.  Only then can the UI components be reliably
+used.  This code does not follow that approach.
+
+The workflows this code supports require very specific UI components that are
+not found in generic libraries.  The interactions we want to support are not
+available in generic libraries.  This code develops from scratch only the
+components that are necessary to implement the workflows of designing and
+operating networks of devices.
+
+This code defines those elements using finite state machines to process the
+events from user input and other software components.  Programming with finite
+state machines allows us to define formally complex behavior that would
+normally be informally defined by branches, functions, object interactions, and
+object inheritance.  Formal definition eliminates much of the unexpected
+behavior that causes defects in the software.
+
+* See: <https://en.wikipedia.org/wiki/Finite-state_machine>
+
+Finite state machines can be represented as a directed graph of labeled nodes and labeled edges
+which can be both be represented visually and in machine readable code.
+
+The network UI uses finite state machines to describe what happens when the software receives
+an input.
+
+**Move FSM**
+
+![Move FSM](networking/move.png)
+
+For example the move FSM describes how devices are moved about the virtual
+canvas.  The FSM diagram above maps out the states and the events that will
+select a device to move.  FSMs traditionally start in the `Start` state.  We
+get a free transition to the `Ready` state by handling the special event called
+`start` and changing state to `Ready`.  When the user presses the mouse button
+if the cursor is over a device the FSM changes state to `Selected1`.  If the
+user then moves the mouse while the button is still pressed the device will be
+moved along with the mouse cursor. When the mouse button is lifted the FSM
+changes to the `Selected1` and then also to the `Selected2` state. This
+implements clicking and dragging devices around the virtual canvas. Clicking on
+the canvas background will return the FSM to the `Ready` state.
+
+* See: [networking/move.yml](networking/move.yml)
+* See: [move.fsm.js](../awx/ui/client/src/network-ui/move.fsm.js)
+
+The move FSM diagram has an equivalent machine readable representation in
+`networking/move.yml`. This representation is useful for comparing the current
+implementation in `move.fsm.js` to the design to see if they are out-of-sync.
+If they are out-of-sync either the design or the implementation can be updated
+depending on if you are changing the design or implementation first.  This
+machine readable representation of the FSM can be used to generate test inputs
+to the FSM to achieve high test coverage of all states and transitions in the
+FSM.
+
+
+**Finite State Machine Implementation**
+
+The implementation of a finite state machine in the network UI is split into
+two parts: the declaration of the states and the event-handlers which may cause
+FSM transitions using `controller.changeState`.
+
+**FSM States**
+
+* See: [networking/README.md](networking/README.md)
+* See: <https://en.wikipedia.org/wiki/Flyweight_pattern>
+* See: <https://en.wikipedia.org/wiki/Singleton_pattern>
+
+States are implemented using an object-oriented style in ES5 using the
+flyweight and singleton patterns. This means that the state objects store no
+information on themselves and that there is only one instance of each state
+class.  All states should provide a `start` and `end` function which will be
+called when a FSM state is entered and exited respectively. Subclassing
+[fsm.State](../awx/ui/client/src/network-ui/fsm.js) will provide empty `start` and `end` functions that
+can be overridden as necessary.
+
+* See: [fsm.js](../awx/ui/client/src/network-ui/fsm.js)
+
+The state variable is stored on another object called an FSMController (which
+should not be confused with an AngularJS controller). The FSMController holds
+all the state for each FSM instance.  If you need more than one copy of an FSM
+(for buttons for instance) use more than one instance of FSMController and
+pass the same FSM starting state to their constructor e.g. `button.Start`.
+Variables other than `state` should not be stored on the FSMController. A
+special variable named `scope` is useful for that. The scope can be used
+to hold arbitrary data that the FSM code will use in addition to the messages
+in the event handlers. In the network UI often the `scope` is a reference
+to the network UI AngularJS controller's scope. In the case of a button
+the scope is a reference to the `Button` model.
+
+* See: [models.js](../awx/ui/client/src/network-ui/models.js)
+
+The following code creates a new instance of `FSMController` using the
+`Button` model as the scope and the `button.Start` state as the initial
+state.
+
+```
+    this.fsm = new fsm.FSMController(this, button.Start, null);
+```
+
+* See: [move.fsm.js](../awx/ui/client/src/network-ui/move.fsm.js)
+
+This code block defines the `_Selected1` class in ES5 style and uses the
+`inherits` NPM module to define that the class is a subclass of `_State`.  We
+also create a single instance (a singleton) of this class named `Selected1`.
+
+```
+    function _Selected1 () {
+        this.name = 'Selected1';
+    }
+    inherits(_Selected1, _State);
+    var Selected1 = new _Selected1();
+    exports.Selected1 = Selected1;
+```
+
+**FSM Event Handlers and Transitions**
+
+After all the states are defined the event handlers for those state classes can be defined.
+We do this to prevent forward references in the file.
+
+* See: [move.fsm.js](../awx/ui/client/src/network-ui/move.fsm.js)
+
+In this code we define an event handler for the `MouseUp` event on the `Selected1` state. This
+code should select a single device if the mouse is over that device.  It should store
+that device somewhere and change to the `Selected2` state.
+
+Event handlers must start with the prefix of `on` and a suffix of the name of the messsage
+type. The special functions `start` and `end` do not follow this rule nor do
+they receive a message.
+
+The event handler must also define its `transitions` as a list so that `./extract.js` can
+find them.
+
+```
+    _Selected1.prototype.onMouseUp = function (controller, msg_type, message) {
+
+        ...
+
+    };
+    _Selected1.prototype.onMouseUp.transitions = ['Selected2'];
+
+```
+
+**FSM Designs**
+
+All the finite state machines for the network UI have been designed using the
+[fsm-designer-svg](https://github.com/benthomasson/fsm-designer-svg) tool
+and their designs are stored in the `networking` directory.
+
+* See: [networking/README.md](networking/README.md)
+
+
+**Data Models**
+
+There are two types of data structures used in the network UI: messages and
+models.  Models are used for long-lived data that is used to render the UI
+whereas messages are used for ephemeral data that is passed from one part of
+the system to another.  Models may be unpacked from or serialized into messages that
+are sent to other FSMControllers in the client or sent over a websocket to the
+server.
+
+* See: [models.js](../awx/ui/client/src/network-ui/models.js)
+
+The models defined in [models.js](../awx/ui/client/src/network-ui/models.js) are:
+
+* Device - a networking device i.e. a router, a switch, or a host
+* Interface - a networking interface
+* Link - a connection between interfaces
+* Button - a UI button
+* ToggleButton - a togglable UI button
+* Task - a playbook task
+* ToolBox - a UI element for holding things that can be placed on the virtual canvas
+
+
+**Message Types**
+
+Message types define the structure of the data that is passed between the server
+and the client and between different parts of the client. This provides a known and
+well defined data structure that can be counted up on the code.
+
+* See: [messages.js](../awx/ui/client/src/network-ui/messages.js)
+
+The messages defined are [messages.js](../awx/ui/client/src/network-ui/messages.js):
+
+* DeviceMove - Device has changed x,y position
+* DeviceCreate - A device was created
+* DeviceDestroy - A device was destroyed
+* DeviceSelected - A device was selected
+* DeviceUnSelected - A device was unselected
+* InterfaceCreate - An interface was created
+* InterfaceLabelEdit - The label of an interface was changed
+* LinkCreate - A link was created
+* LinkDestroy - A link was destroyed
+* LinkSelected - A link was selected
+* LinkUnSelected -  A link was unselected
+* MultipleMessage - A collection of messages that should be handled together
+* Coverage - A coverage report
+* MouseEvent - A generic mouse event
+* MouseWheelEvent  - A mouse wheel event
+* KeyEvent - A key press event
+* StartRecording - Start recording user interactions
+* StopRecording - Stop recording user interactions
+* ViewPort - Update the view port onto the virtual canvas
+* NewDevice - Request for a new device
+* PasteDevice - Paste a device from a toolbox
+
+
+Server-Side Details
+-----------------------
+
+The Network UI is a UX driven feature to provide a graphical user
+experience that fits well into the network engineer's normal workflow. Their
+normal workflow includes a diagram drawn in a graphical drawing program, a
+spreadsheet, and the command line interface of their network gear.  Network
+architects design the network on the graphical diagram and then hand off the
+architecture to network operators who implement the architecture on the network
+using spreadsheets to manage their data and manually converting the data into
+CLI commands using their networking expertise and expertise with their physical
+gear.
+
+The server-side code supports the persistence needed to provide this graphical
+user experience of architecting a network and using that information along with
+additional information (stored in vars files) to configure the network devices
+using the CLI or NETCONF using Ansible playbooks and roles.
+
+Network UI Data Schema
+----------------------
+
+For the 3.3 release the persistence needed includes the position information of
+the devices on the virtual canvas and the type of the devices as well as
+information about the interfaces on the devices and the links connecting those
+interfaces.
+
+These requirements determine the database schema needed for the network UI which
+requires these models: Topology, Device, Interface, Link, Client, and TopologyInventory.
+
+![Models](networking/models.png)
+
+This diagram shows the relationships between the models in the Network UI schema.
+
+The models are:
+
+* Device - a host, switch, router, or other networking device
+* Interface - a connection point on a device for a link
+* Link - a physical connection between two devices to their respective interfaces
+* Topology - a collection of devices and links
+* TopologyInventory - a mapping between topologies and Tower inventories
+* Client - a UI client session
+
+
+Network UI Websocket Protocol
+-----------------------------
+
+Persistence for the network UI canvas state is implemented using an
+asynchronous websocket protocol to send information from the client to the
+server and vice-versa.  This two-way communication was chosen to support future
+features for streaming data to the canvas, broadcast messaging between clients,
+and for interaction performance on the UI.
+
+
+Messages
+--------
+
+JSON messages are passed over the `/network_ui/topology` websocket between the
+test client and the test server.  The protocol that is used for all messages is
+in ABNF (RFC5234):
+
+
+    message_type    =  'DeviceMove' / 'DeviceCreate' / 'DeviceDestroy' / 'DeviceLabelEdit' / 'DeviceSelected' / 'DeviceUnSelected' / 'InterfaceCreate' / 'InterfaceLabelEdit' / 'LinkLabelEdit' / 'LinkCreate' / 'LinkDestroy' / 'LinkSelected' / 'LinkUnSelected' / 'MultipleMessage' / 'Snapshot'
+    message_data    = '{' 'msg_type' ': ' message_type ', ' key-value *( ', ' key-value ) '}'
+    message         = '[ id , ' posint ']' / '[ topology_id , ' posint ']' / '[' message_type ', ' message_data ']'
+
+See https://github.com/AndyA/abnfgen/blob/master/andy/json.abnf for the rest of
+the JSON ABNF.
+
+See [networking/messages.yml](networking/messages.yml) for the allowable keys and
+values for each message type.
+
+
+Initially when the websocket is first opened the server will send four messages
+to the client.  These are:
+
+* the client id using the `id` message type.
+* the topology id using the `topology` message type.
+* a Topology record containing data for the canvas itself.
+* a Snapshot message containing all the data of the data on the canvas.
+
+As the user interacts with the canvas messages will be generated by the client
+and the `network_ui.consumers.NetworkEvents` class will update the models that
+represent the canvas.
+
+
+
+Persistence
+-----------
+
+The class `awx.network_uiconsumers.NetworkEvents` provides persistence for the Network UI canvas.
+It does so by providing message handlers that handle storage of the canvas change events
+into the database. Each event has a message handle with name `onX` where `X` is the name of the message
+type.  The handlers use the `filter/values_list`, `filter/values`, `filter/update`, and `filter/delete`
+patterns to update the data in the database quickly with a constant O(1) number of queries per event
+often with only one query needed. With `filter/update` and `filter/delete` all the work is done
+in the database and Python never needs to instaniate and garbage collect the model objects.
+
+Bulk operations (`filter/values`) in `send_snapshot` are used to produce a constant number of
+queries produce a snapshot when the canvas is first loaded.  This method avoids creating
+the model objects since it only produces dicts that are JSON serializable which are bundled
+together for the `Snapshot` message type.
+
+This method of persistence uses Django as a database query-compiler for transforms from
+the event types to the database types.  Using Django in this way is very performant since
+Python does very little work processing the data and when possible the data never leaves
+the database.
+
+
+Client Tracking
+---------------
+
+Each user session to the network UI canvas is tracked with the `Client` model.  Multiple
+clients can view and interact with the network UI canvas at a time.  They will see each other's
+edits to the canvas in real time.  This works by broadcasting the canvas change events to
+all clients viewing the same topology.
+
+```
+    # Send to all clients editing the topology
+    Group("topology-%s" % message.channel_session['topology_id']).send({"text": message['text']})
+```
+
+API
+---
+
+There is no user accessible API for this feature in the 3.3 release.
--- a/docs/networking/README.md
+++ b/docs/networking/README.md
@ -0,0 +1,100 @@
+
+
+Finite State Machine Designs
+============================
+
+This directory contains the finite state machine designs that were used to
+generate the skeleton of the javascript implementations and can be used to
+check that the implementations still match the designs.
+
+
+**Machine Readable FSM Schema**
+
+The machine readable FSM schema contains three top-level elements: `name`, `states`, and `transitions`.
+* The `name` element is a string.
+* The `states` element contains a list of `state` elements which have attributes `id`, `label`, and `x`, and `y`.
+* The `transitions` element contains a list of `transition` elements which have attributes `from_state`, `to_state`, and `label`.
+
+
+**Design Diagrams**
+
+The diagrams below are visual representations of the finite state machine designs in this directory.
+The equivalent machine readable representations are linked as well.
+
+---
+
+
+**Button FSM**
+* See: button.yml
+
+The button FSM describes how a button works. The key insight here is that a button is not
+clicked if the mouse is not over the button on both the `MouseDown` and `MouseUp` events. Moving
+the mouse off the button before `MouseUp` is not a click.
+
+![Button FSM](button.png)
+
+---
+
+**Buttons FSM**
+* See: buttons.yml
+
+The buttons FSM distributes events to the buttons which each have their own FSM.
+
+![Buttons FSM](buttons.png)
+
+---
+
+**Hot Keys FSM**
+* See: hotkeys.yml
+
+The hot keys FSM handles key events and generates new events like `NewLink` to implement
+hot keys.
+
+![Hot Keys FSM](hotkeys.png)
+
+---
+
+**Mode FSM**
+* See: mode.yml
+
+The mode FSM controls the overall mode of the network UI application.
+
+![Mode](mode.png)
+
+---
+
+**Move FSM**
+* See: move.yml
+
+The move FSM controls placement of devices as well as editing the device labels.
+
+![Move](move.png)
+
+---
+
+**Time FSM**
+* See: time.yml
+
+The time FSM controls undo/redo functionality of the network UI.
+
+![Time](time.png)
+
+---
+
+**Toolbox FSM**
+* See: toolbox.yml
+
+The toolbox FSM controls the drag-and-drop toolboxes and allow placement of new devices, applications,
+racks, and sites onto the canvas.
+
+![Toolbox](toolbox.png)
+
+---
+
+**View FSM**
+* See: view.yml
+
+The view FSM controls the panning and scaling of the the virtual canvas through clicking-and-dragging
+of the background and scrolling the mousewheel.
+
+![View](view.png)
--- a/docs/networking/animation.yml
+++ b/docs/networking/animation.yml
@ -0,0 +1,29 @@
+diagram_id: 58
+name: animation_fsm
+states:
+- id: 4
+  label: Cancelled
+  x: 590
+  y: 602
+- id: 3
+  label: Completed
+  x: 225
+  y: 604
+- id: 2
+  label: Running
+  x: 418
+  y: 362
+- id: 1
+  label: Start
+  x: 454
+  y: 158
+transitions:
+- from_state: Running
+  label: onAnimationCancelled
+  to_state: Cancelled
+- from_state: Running
+  label: onAnimationCompleted
+  to_state: Completed
+- from_state: Start
+  label: start
+  to_state: Running
--- a/docs/networking/button.png
+++ b/docs/networking/button.png
--- a/docs/networking/button.yml
+++ b/docs/networking/button.yml
@ -0,0 +1,43 @@
+diagram_id: 66
+name: 'button_fsm'
+finite_state_machine_id: 12
+states:
+- id: 3
+  label: Clicked
+  x: 331
+  y: 568
+- id: 5
+  label: Disabled
+  x: 719
+  y: 283
+- id: 4
+  label: Pressed
+  x: 606
+  y: 563
+- id: 1
+  label: Ready
+  x: 471
+  y: 376
+- id: 2
+  label: Start
+  x: 468
+  y: 170
+transitions:
+- from_state: Clicked
+  label: start
+  to_state: Ready
+- from_state: Disabled
+  label: onEnable
+  to_state: Ready
+- from_state: Pressed
+  label: onMouseUp
+  to_state: Clicked
+- from_state: Ready
+  label: onDisable
+  to_state: Disabled
+- from_state: Ready
+  label: onMouseDown
+  to_state: Pressed
+- from_state: Start
+  label: start
+  to_state: Ready
--- a/docs/networking/buttons.png
+++ b/docs/networking/buttons.png
--- a/docs/networking/buttons.yml
+++ b/docs/networking/buttons.yml
@ -0,0 +1,28 @@
+app: buttons_fsm
+finite_state_machine_id: 7
+panX: 133
+panY: 41
+scaleXY: 1
+states:
+- label: Start
+  size: 100
+  x: 392
+  y: 88
+- label: Ready
+  size: 100
+  x: 392
+  y: 281
+- label: ButtonPressed
+  size: 100
+  x: 394
+  y: 491
+transitions:
+- from_state: Start
+  label: start
+  to_state: Ready
+- from_state: Ready
+  label: onMouseDown
+  to_state: ButtonPressed
+- from_state: ButtonPressed
+  label: onMouseUp
+  to_state: Ready
--- a/docs/networking/details.panel.png
+++ b/docs/networking/details.panel.png
--- a/docs/networking/details.panel.yml
+++ b/docs/networking/details.panel.yml
@ -0,0 +1,26 @@
+diagram_id: 70
+finite_state_machine_id: 21
+name: diagram
+states:
+- id: 1
+  label: Start
+  x: 590
+  y: 233
+- id: 2
+  label: Collapsed
+  x: 594
+  y: 490
+- id: 3
+  label: Expanded
+  x: 919
+  y: 491
+transitions:
+- from_state: Start
+  label: start
+  to_state: Collapsed
+- from_state: Expanded
+  label: onDetailsPanelClose
+  to_state: Collapsed
+- from_state: Collapsed
+  label: onDetailsPanel
+  to_state: Expanded
--- a/docs/networking/device.detail.png
+++ b/docs/networking/device.detail.png
--- a/docs/networking/device.detail.yml
+++ b/docs/networking/device.detail.yml
@ -0,0 +1,19 @@
+finite_state_machine_id: 19
+name: device_detail_fsm
+states:
+- id: 2
+  label: Ready
+  x: 517
+  y: 588
+- id: 3
+  label: Disable
+  x: 770
+  y: 455
+- id: 1
+  label: Start
+  x: 507
+  y: 336
+transitions:
+- from_state: Start
+  label: start
+  to_state: Ready
--- a/docs/networking/group.png
+++ b/docs/networking/group.png
--- a/docs/networking/group.yml
+++ b/docs/networking/group.yml
@ -0,0 +1,119 @@
+diagram_id: 61
+finite_state_machine_id: 5
+name: group_fsm
+states:
+- id: 12
+  label: ContextMenu
+  x: 1228
+  y: -74
+- id: 3
+  label: CornerSelected
+  x: 526
+  y: 554
+- id: 8
+  label: Disable
+  x: 497
+  y: 84
+- id: 9
+  label: EditLabel
+  x: 1130
+  y: 112
+- id: 6
+  label: Move
+  x: 1297
+  y: 786
+- id: 11
+  label: Placing
+  x: 299
+  y: 300
+- id: 7
+  label: Ready
+  x: 733
+  y: 304
+- id: 1
+  label: Resize
+  x: 571
+  y: 911
+- id: 4
+  label: Selected1
+  x: 839
+  y: 640
+- id: 10
+  label: Selected2
+  x: 1179
+  y: 435
+- id: 5
+  label: Selected3
+  x: 1528
+  y: 360
+- id: 2
+  label: Start
+  x: 744
+  y: 69
+transitions:
+- from_state: ContextMenu
+  label: onLabelEdit
+  to_state: EditLabel
+- from_state: ContextMenu
+  label: onMouseDown
+  to_state: Ready
+- from_state: CornerSelected
+  label: onMouseMove
+  to_state: Resize
+- from_state: CornerSelected
+  label: onMouseUp
+  to_state: Selected1
+- from_state: EditLabel
+  label: onKeyDown
+  to_state: Selected2
+- from_state: EditLabel
+  label: onMouseDown
+  to_state: Ready
+- from_state: Move
+  label: onMouseDown
+  to_state: Selected1
+- from_state: Move
+  label: onMouseUp
+  to_state: Selected2
+- from_state: Placing
+  label: onMouseDown
+  to_state: Resize
+- from_state: Ready
+  label: onMouseDown
+  to_state: CornerSelected
+- from_state: Ready
+  label: onMouseDown
+  to_state: Selected1
+- from_state: Ready
+  label: onNewGroup
+  to_state: Placing
+- from_state: Resize
+  label: onMouseUp
+  to_state: Selected1
+- from_state: Selected1
+  label: onMouseMove
+  to_state: Move
+- from_state: Selected1
+  label: onMouseUp
+  to_state: Selected2
+- from_state: Selected2
+  label: onKeyDown
+  to_state: Ready
+- from_state: Selected2
+  label: onMouseDown
+  to_state: Ready
+- from_state: Selected2
+  label: onMouseDown
+  to_state: Selected3
+- from_state: Selected2
+  label: onNewGroup
+  to_state: Ready
+- from_state: Selected3
+  label: onMouseMove
+  to_state: Move
+- from_state: Selected3
+  label: onMouseUp
+  to_state: ContextMenu
+- from_state: Start
+  label: start
+  to_state: Ready
--- a/docs/networking/hotkeys.png
+++ b/docs/networking/hotkeys.png
--- a/docs/networking/hotkeys.yml
+++ b/docs/networking/hotkeys.yml
@ -0,0 +1,25 @@
+finite_state_machine_id: 1
+name: hotkeys_fsm
+states:
+- id: 2
+  label: Enabled
+  x: 585
+  y: 396
+- id: 1
+  label: Start
+  x: 585
+  y: 160
+- id: 3
+  label: Disabled
+  x: 331
+  y: 408
+transitions:
+- from_state: Enabled
+  label: onDisable
+  to_state: Disabled
+- from_state: Disabled
+  label: onEnable
+  to_state: Enabled
+- from_state: Start
+  label: start
+  to_state: Enabled
--- a/docs/networking/keybindings.png
+++ b/docs/networking/keybindings.png
--- a/docs/networking/keybindings.yml
+++ b/docs/networking/keybindings.yml
@ -0,0 +1,38 @@
+diagram_id: 68
+finite_state_machine_id: 18
+name: diagram
+states:
+- id: 1
+  label: Enabled
+  x: 842
+  y: 533
+- id: 2
+  label: Start
+  x: 839
+  y: 270
+- id: 3
+  label: Disabled
+  x: 1412
+  y: 522
+transitions:
+- from_state: Start
+  label: start
+  to_state: Enabled
+- from_state: Disabled
+  label: onBindDocument
+  to_state: Enabled
+- from_state: Enabled
+  label: onUnbindDocument
+  to_state: Disabled
+- from_state: Disabled
+  label: onDetailsPanelClose
+  to_state: Enabled
+- from_state: Enabled
+  label: onDetailsPanel
+  to_state: Disabled
+- from_state: Enabled
+  label: onSearchDropdown
+  to_state: Disabled
+- from_state: Disabled
+  label: onSearchDropdownClose
+  to_state: Enabled
--- a/docs/networking/link.png
+++ b/docs/networking/link.png
--- a/docs/networking/link.yml
+++ b/docs/networking/link.yml
@ -0,0 +1,42 @@
+finite_state_machine_id: 4
+name: link_fsm
+states:
+- id: 5
+  label: Selecting
+  x: -429
+  y: 63
+- id: 2
+  label: Start
+  x: 15
+  y: -221
+- id: 4
+  label: Connecting
+  x: -429
+  y: 466
+- id: 3
+  label: Connected
+  x: 47
+  y: 453
+- id: 1
+  label: Ready
+  x: 26
+  y: 61
+transitions:
+- from_state: Ready
+  label: onNewLink
+  to_state: Selecting
+- from_state: Selecting
+  label: onMouseUp
+  to_state: Connecting
+- from_state: Connecting
+  label: onMouseUp
+  to_state: Connected
+- from_state: Connecting
+  label: onMouseUp
+  to_state: Ready
+- from_state: Connected
+  label: start
+  to_state: Ready
+- from_state: Start
+  label: start
+  to_state: Ready
--- a/docs/networking/messages.yml
+++ b/docs/networking/messages.yml
@ -0,0 +1,19 @@
+messages:
+    - {msg_type: DeviceMove, fields: [msg_type, sender, id, x, y, previous_x, previous_y]}
+    - {msg_type: DeviceCreate, fields: [msg_type, sender, id, x, y, name, type, host_id]}
+    - {msg_type: DeviceDestroy, fields: [msg_type, sender, id, previous_x, previous_y, previous_name, previous_type, previous_host_id]}
+    - {msg_type: DeviceLabelEdit, fields: [msg_type, sender, id, name, previous_name]}
+    - {msg_type: DeviceSelected, fields: [msg_type, sender, id]}
+    - {msg_type: DeviceUnSelected, fields: [msg_type, sender, id]}
+    - {msg_type: InterfaceCreate, fields: [msg_type, sender, device_id, id, name]}
+    - {msg_type: InterfaceLabelEdit, fields: [msg_type, sender, id, device_id, name, previous_name]}
+    - {msg_type: LinkLabelEdit, fields: [msg_type, sender, id, name, previous_name]}
+    - {msg_type: LinkCreate, fields: [msg_type, id, sender, name, from_device_id, to_device_id, from_interface_id, to_interface_id]}
+    - {msg_type: LinkDestroy, fields: [msg_type, id, sender, name, from_device_id, to_device_id, from_interface_id, to_interface_id]}
+    - {msg_type: LinkSelected, fields: [msg_type, sender, id]}
+    - {msg_type: LinkUnSelected, fields: [msg_type, sender, id]}
+    - {msg_type: MultipleMessage, fields: [msg_type, sender, messages]}
+    - {msg_type: Snapshot, fields: [msg_type, sender, devices, links, order, trace_id]}
+    - {msg_type: id, type: int}
+    - {msg_type: topology_id, type: int}
+    - {msg_type: Topology, fields: [topology_id, name, panX, panY, scale, link_id_seq, device_id_seq]}
--- a/docs/networking/mode.png
+++ b/docs/networking/mode.png
--- a/docs/networking/mode.yml
+++ b/docs/networking/mode.yml
@ -0,0 +1,96 @@
+diagram_id: 68
+finite_state_machine_id: 9
+name: mode_fsm
+states:
+- id: 7
+  label: Device
+  x: 558
+  y: 821
+- id: 2
+  label: Interface
+  x: 340
+  y: 1053
+- id: 5
+  label: MultiSite
+  x: 569
+  y: -88
+- id: 4
+  label: Process
+  x: 833
+  y: 1051
+- id: 6
+  label: Rack
+  x: 571
+  y: 486
+- id: 3
+  label: Site
+  x: 564
+  y: 201
+- id: 1
+  label: Start
+  x: 568
+  y: -379
+transitions:
+- from_state: Device
+  label: onMouseWheel
+  to_state: Process
+- from_state: Device
+  label: onMouseWheel
+  to_state: Rack
+- from_state: Device
+  label: onMouseWheel
+  to_state: Interface
+- from_state: Device
+  label: onScaleChanged
+  to_state: Interface
+- from_state: Device
+  label: onScaleChanged
+  to_state: Rack
+- from_state: Device
+  label: onScaleChanged
+  to_state: Process
+- from_state: Interface
+  label: onMouseWheel
+  to_state: Device
+- from_state: Interface
+  label: onScaleChanged
+  to_state: Device
+- from_state: MultiSite
+  label: onMouseWheel
+  to_state: Site
+- from_state: MultiSite
+  label: onScaleChanged
+  to_state: Site
+- from_state: Process
+  label: onMouseWheel
+  to_state: Device
+- from_state: Process
+  label: onScaleChanged
+  to_state: Device
+- from_state: Rack
+  label: onMouseWheel
+  to_state: Site
+- from_state: Rack
+  label: onMouseWheel
+  to_state: Device
+- from_state: Rack
+  label: onScaleChanged
+  to_state: Site
+- from_state: Rack
+  label: onScaleChanged
+  to_state: Device
+- from_state: Site
+  label: onMouseWheel
+  to_state: MultiSite
+- from_state: Site
+  label: onMouseWheel
+  to_state: Rack
+- from_state: Site
+  label: onScaleChanged
+  to_state: MultiSite
+- from_state: Site
+  label: onScaleChanged
+  to_state: Rack
+- from_state: Start
+  label: start
+  to_state: MultiSite
--- a/docs/networking/models.png
+++ b/docs/networking/models.png
--- a/docs/networking/models.yml
+++ b/docs/networking/models.yml
@ -0,0 +1,130 @@
+app: awx.network_ui
+external_models: []
+models:
+- display: name
+  fields:
+  - name: device_id
+    pk: true
+    type: AutoField
+  - name: topology
+    ref: Topology
+    ref_field: topology_id
+    type: ForeignKey
+  - len: 200
+    name: name
+    type: CharField
+  - name: x
+    type: IntegerField
+  - name: y
+    type: IntegerField
+  - name: id
+    type: IntegerField
+  - len: 200
+    name: device_type
+    type: CharField
+  - default: 0
+    name: interface_id_seq
+    type: IntegerField
+  - default: 0
+    name: host_id
+    type: IntegerField
+  name: Device
+  x: 348
+  y: 124
+- fields:
+  - name: link_id
+    pk: true
+    type: AutoField
+  - name: from_device
+    ref: Device
+    ref_field: device_id
+    related_name: from_link
+    type: ForeignKey
+  - name: to_device
+    ref: Device
+    ref_field: device_id
+    related_name: to_link
+    type: ForeignKey
+  - name: from_interface
+    ref: Interface
+    ref_field: interface_id
+    related_name: from_link
+    type: ForeignKey
+  - name: to_interface
+    ref: Interface
+    ref_field: interface_id
+    related_name: to_link
+    type: ForeignKey
+  - name: id
+    type: IntegerField
+  - len: 200
+    name: name
+    type: CharField
+  name: Link
+  x: 731
+  y: -33
+- display: name
+  fields:
+  - name: topology_id
+    pk: true
+    type: AutoField
+  - len: 200
+    name: name
+    type: CharField
+  - name: scale
+    type: FloatField
+  - name: panX
+    type: FloatField
+  - name: panY
+    type: FloatField
+  - default: 0
+    name: device_id_seq
+    type: IntegerField
+  - default: 0
+    name: link_id_seq
+    type: IntegerField
+  name: Topology
+  x: 111
+  y: 127
+- fields:
+  - name: client_id
+    pk: true
+    type: AutoField
+  name: Client
+  x: -162
+  y: 282
+- display: name
+  fields:
+  - name: interface_id
+    pk: true
+    type: AutoField
+  - name: device
+    ref: Device
+    ref_field: device_id
+    type: ForeignKey
+  - len: 200
+    name: name
+    type: CharField
+  - name: id
+    type: IntegerField
+  name: Interface
+  x: 977
+  y: 312
+- fields:
+  - name: topology_inventory_id
+    pk: true
+    type: AutoField
+  - name: topology
+    ref: Topology
+    ref_field: topology_id
+    type: ForeignKey
+  - name: inventory_id
+    type: IntegerField
+  name: TopologyInventory
+  x: -204
+  y: 12
+modules: []
+view:
+  panX: 213.729555519212
+  panY: 189.446959094643
+  scaleXY: 0.69
--- a/docs/networking/move.png
+++ b/docs/networking/move.png
--- a/docs/networking/move.readonly.png
+++ b/docs/networking/move.readonly.png
--- a/docs/networking/move.readonly.yml
+++ b/docs/networking/move.readonly.yml
@ -0,0 +1,65 @@
+diagram_id: 91
+name: diagram
+states:
+- id: 0
+  label: ContextMenu
+  x: 826
+  y: 1008
+- id: 1
+  label: Disable
+  x: 914
+  y: 115
+- id: 5
+  label: Ready
+  x: 702
+  y: 327
+- id: 6
+  label: Selected1
+  x: 397
+  y: 332
+- id: 7
+  label: Selected2
+  x: 268
+  y: 735
+- id: 8
+  label: Selected3
+  x: 225
+  y: 1021
+- id: 9
+  label: Start
+  x: 704
+  y: 128
+transitions:
+- from_state: ContextMenu
+  label: onDetailsPanel
+  to_state: Selected2
+- from_state: ContextMenu
+  label: onMouseDown
+  to_state: Selected2
+- from_state: Ready
+  label: onMouseDown
+  to_state: Selected1
+- from_state: Selected1
+  label: onMouseUp
+  to_state: Selected2
+- from_state: Selected2
+  label: onKeyDown
+  to_state: Ready
+- from_state: Selected2
+  label: onMouseDown
+  to_state: Selected3
+- from_state: Selected2
+  label: onMouseDown
+  to_state: Ready
+- from_state: Selected3
+  label: ''
+  to_state: Selected3
+- from_state: Selected3
+  label: onMouseMove
+  to_state: Selected2
+- from_state: Selected3
+  label: onMouseUp
+  to_state: ContextMenu
+- from_state: Start
+  label: start
+  to_state: Ready
--- a/docs/networking/move.yml
+++ b/docs/networking/move.yml
@ -0,0 +1,107 @@
+diagram_id: 87
+name: move
+states:
+- id: 8
+  label: ContextMenu
+  x: 826
+  y: 1008
+- id: 0
+  label: Disable
+  x: 914
+  y: 115
+- id: 6
+  label: EditLabel
+  x: 765
+  y: 684
+- id: 4
+  label: Move
+  x: 118
+  y: 594
+- id: 5
+  label: Placing
+  x: 263
+  y: 89
+- id: 2
+  label: Ready
+  x: 702
+  y: 327
+- id: 3
+  label: Selected1
+  x: 397
+  y: 332
+- id: 7
+  label: Selected2
+  x: 268
+  y: 735
+- id: 9
+  label: Selected3
+  x: 361
+  y: 961
+- id: 1
+  label: Start
+  x: 704
+  y: 128
+transitions:
+- from_state: ContextMenu
+  label: onDetailsPanel
+  to_state: Selected2
+- from_state: ContextMenu
+  label: onLabelEdit
+  to_state: EditLabel
+- from_state: ContextMenu
+  label: onMouseDown
+  to_state: Selected2
+- from_state: EditLabel
+  label: onKeyDown
+  to_state: Selected2
+- from_state: EditLabel
+  label: onMouseDown
+  to_state: Ready
+- from_state: Move
+  label: onMouseDown
+  to_state: Selected1
+- from_state: Move
+  label: onMouseUp
+  to_state: Selected1
+- from_state: Placing
+  label: onMouseDown
+  to_state: Selected1
+- from_state: Placing
+  label: onMouseMove
+  to_state: Move
+- from_state: Ready
+  label: onMouseDown
+  to_state: Selected1
+- from_state: Ready
+  label: onNewDevice
+  to_state: Placing
+- from_state: Ready
+  label: onPasteDevice
+  to_state: Selected2
+- from_state: Selected1
+  label: onMouseMove
+  to_state: Move
+- from_state: Selected1
+  label: onMouseUp
+  to_state: Selected2
+- from_state: Selected2
+  label: onKeyDown
+  to_state: Ready
+- from_state: Selected2
+  label: onMouseDown
+  to_state: Selected3
+- from_state: Selected2
+  label: onMouseDown
+  to_state: Ready
+- from_state: Selected2
+  label: onNewDevice
+  to_state: Ready
+- from_state: Selected3
+  label: onMouseMove
+  to_state: Move
+- from_state: Selected3
+  label: onMouseUp
+  to_state: ContextMenu
+- from_state: Start
+  label: start
+  to_state: Ready
--- a/docs/networking/null.png
+++ b/docs/networking/null.png
--- a/docs/networking/null.yml
+++ b/docs/networking/null.yml
@ -0,0 +1,15 @@
+finite_state_machine_id: 17
+name: null_fsm
+states:
+- id: 1
+  label: Start
+  x: 391
+  y: 132
+- id: 2
+  label: Ready
+  x: 402
+  y: 346
+transitions:
+- from_state: Start
+  label: start
+  to_state: Ready
--- a/docs/networking/pipeline.png
+++ b/docs/networking/pipeline.png
--- a/docs/networking/pipeline.yml
+++ b/docs/networking/pipeline.yml
@ -0,0 +1,233 @@
+channels:
+- from_fsm: buttons_fsm
+  from_fsm_id: 7
+  inbox: ''
+  outbox: ''
+  to_fsm: button_fsm
+  to_fsm_id: 12
+  type: ''
+- from_fsm: buttons_fsm
+  from_fsm_id: 7
+  inbox: ''
+  outbox: ''
+  to_fsm: toolbox_fsm
+  to_fsm_id: 14
+  type: ''
+- from_fsm: details_panel_fsm
+  from_fsm_id: 21
+  inbox: ''
+  outbox: ''
+  to_fsm: move_fsm
+  to_fsm_id: 3
+  type: ''
+- from_fsm: device_detail_fsm
+  from_fsm_id: 19
+  inbox: ''
+  outbox: ''
+  to_fsm: view_fsm
+  to_fsm_id: 2
+  type: ''
+- from_fsm: group_fsm
+  from_fsm_id: 5
+  inbox: ''
+  outbox: ''
+  to_fsm: stream_fsm
+  to_fsm_id: 20
+  type: ''
+- from_fsm: hotkeys_fsm
+  from_fsm_id: 1
+  inbox: ''
+  outbox: ''
+  to_fsm: null_fsm
+  to_fsm_id: 17
+  type: ''
+- from_fsm: keybindings_fsm
+  from_fsm_id: 18
+  inbox: ''
+  outbox: ''
+  to_fsm: hotkeys_fsm
+  to_fsm_id: 1
+  type: ''
+- from_fsm: link_fsm
+  from_fsm_id: 4
+  inbox: ''
+  outbox: ''
+  to_fsm: details_panel_fsm
+  to_fsm_id: 21
+  type: ''
+- from_fsm: mode_fsm
+  from_fsm_id: 9
+  inbox: ''
+  outbox: ''
+  to_fsm: time_fsm
+  to_fsm_id: 8
+  type: ''
+- from_fsm: move_fsm
+  from_fsm_id: 3
+  inbox: ''
+  outbox: ''
+  to_fsm: device_detail_fsm
+  to_fsm_id: 19
+  type: ''
+- from_fsm: rack_fsm
+  from_fsm_id: 6
+  inbox: ''
+  outbox: ''
+  to_fsm: group_fsm
+  to_fsm_id: 5
+  type: ''
+- from_fsm: site_fsm
+  from_fsm_id: 22
+  inbox: ''
+  outbox: ''
+  to_fsm: rack_fsm
+  to_fsm_id: 6
+  type: ''
+- from_fsm: stream_fsm
+  from_fsm_id: 20
+  inbox: ''
+  outbox: ''
+  to_fsm: link_fsm
+  to_fsm_id: 4
+  type: ''
+- from_fsm: test_fsm
+  from_fsm_id: 23
+  inbox: ''
+  outbox: ''
+  to_fsm: mode_fsm
+  to_fsm_id: 9
+  type: ''
+- from_fsm: time_fsm
+  from_fsm_id: 8
+  inbox: ''
+  outbox: ''
+  to_fsm: buttons_fsm
+  to_fsm_id: 7
+  type: ''
+- from_fsm: toolbox_fsm
+  from_fsm_id: 14
+  inbox: ''
+  outbox: ''
+  to_fsm: site_fsm
+  to_fsm_id: 22
+  type: ''
+- from_fsm: view_fsm
+  from_fsm_id: 2
+  inbox: ''
+  outbox: ''
+  to_fsm: keybindings_fsm
+  to_fsm_id: 18
+  type: ''
+diagram_id: 85
+fsms:
+- id: 12
+  name: button_fsm
+  x1: -2438
+  x2: -3026
+  y1: -934
+  y2: -1532
+- id: 7
+  name: buttons_fsm
+  x1: -2650
+  x2: -2850
+  y1: -16
+  y2: -619
+- id: 21
+  name: details_panel_fsm
+  x1: 5669
+  x2: 5140
+  y1: -64
+  y2: -521
+- id: 19
+  name: device_detail_fsm
+  x1: 7667
+  x2: 7214
+  y1: -110
+  y2: -562
+- id: 5
+  name: group_fsm
+  x1: 3685
+  x2: 2256
+  y1: 278
+  y2: -906
+- id: 1
+  name: hotkeys_fsm
+  x1: 9692
+  x2: 9281
+  y1: -124
+  y2: -549
+- id: 18
+  name: keybindings_fsm
+  x1: 9223
+  x2: 8370
+  y1: -71
+  y2: -614
+- id: 4
+  name: link_fsm
+  x1: 5080
+  x2: 4436
+  y1: 154
+  y2: -732
+- id: 9
+  name: mode_fsm
+  x1: -3760
+  x2: -4453
+  y1: 192
+  y2: -1439
+- id: 3
+  name: move_fsm
+  x1: 6968
+  x2: 5813
+  y1: 146
+  y2: -935
+- id: 17
+  name: null_fsm
+  x1: 10125
+  x2: 9925
+  y1: -129
+  y2: -543
+- id: 6
+  name: rack_fsm
+  x1: 2214
+  x2: 1047
+  y1: 127
+  y2: -753
+- id: 22
+  name: site_fsm
+  x1: 964
+  x2: -190
+  y1: 128
+  y2: -768
+- id: 20
+  name: stream_fsm
+  x1: 4376
+  x2: 3868
+  y1: 56
+  y2: -643
+- id: 23
+  name: test_fsm
+  x1: -4569
+  x2: -5140
+  y1: 72
+  y2: -863
+- id: 8
+  name: time_fsm
+  x1: -3122
+  x2: -3693
+  y1: -69
+  y2: -553
+- id: 14
+  name: toolbox_fsm
+  x1: -680
+  x2: -1722
+  y1: 265
+  y2: -904
+- id: 2
+  name: view_fsm
+  x1: 8311
+  x2: 7734
+  y1: -25
+  y2: -684
+name: diagram
+states: []
+transitions: []
--- a/docs/networking/rack.png
+++ b/docs/networking/rack.png
--- a/docs/networking/rack.yml
+++ b/docs/networking/rack.yml
@ -0,0 +1,83 @@
+diagram_id: 65
+finite_state_machine_id: 6
+name: rack_fsm
+states:
+- id: 9
+  label: ContextMenu
+  x: 898
+  y: 1016
+- id: 2
+  label: Disable
+  x: 760
+  y: 468
+- id: 7
+  label: EditLabel
+  x: 600
+  y: 934
+- id: 8
+  label: Move
+  x: -69
+  y: 861
+- id: 1
+  label: Ready
+  x: 532
+  y: 560
+- id: 4
+  label: Selected1
+  x: 214
+  y: 566
+- id: 5
+  label: Selected2
+  x: 220
+  y: 810
+- id: 6
+  label: Selected3
+  x: 249
+  y: 1047
+- id: 3
+  label: Start
+  x: 582
+  y: 334
+transitions:
+- from_state: ContextMenu
+  label: onLabelEdit
+  to_state: EditLabel
+- from_state: ContextMenu
+  label: onMouseDown
+  to_state: Ready
+- from_state: EditLabel
+  label: onKeyDown
+  to_state: Selected2
+- from_state: EditLabel
+  label: onMouseDown
+  to_state: Ready
+- from_state: Move
+  label: onMouseUp
+  to_state: Selected2
+- from_state: Ready
+  label: onMouseDown
+  to_state: Selected1
+- from_state: Selected1
+  label: onMouseMove
+  to_state: Move
+- from_state: Selected1
+  label: onMouseUp
+  to_state: Selected2
+- from_state: Selected2
+  label: onKeyDown
+  to_state: Ready
+- from_state: Selected2
+  label: onMouseDown
+  to_state: Ready
+- from_state: Selected2
+  label: onMouseDown
+  to_state: Selected3
+- from_state: Selected3
+  label: onMouseMove
+  to_state: Move
+- from_state: Selected3
+  label: onMouseUp
+  to_state: ContextMenu
+- from_state: Start
+  label: start
+  to_state: Ready
--- a/docs/networking/site.png
+++ b/docs/networking/site.png
--- a/docs/networking/site.yml
+++ b/docs/networking/site.yml
@ -0,0 +1,83 @@
+diagram_id: 63
+finite_state_machine_id: 22
+name: site_fsm
+states:
+- id: 9
+  label: ContextMenu
+  x: 887
+  y: 1031
+- id: 2
+  label: Disable
+  x: 760
+  y: 468
+- id: 7
+  label: EditLabel
+  x: 600
+  y: 934
+- id: 8
+  label: Move
+  x: -69
+  y: 861
+- id: 1
+  label: Ready
+  x: 532
+  y: 560
+- id: 4
+  label: Selected1
+  x: 214
+  y: 566
+- id: 5
+  label: Selected2
+  x: 220
+  y: 810
+- id: 6
+  label: Selected3
+  x: 249
+  y: 1047
+- id: 3
+  label: Start
+  x: 582
+  y: 334
+transitions:
+- from_state: ContextMenu
+  label: onLabelEdit
+  to_state: EditLabel
+- from_state: ContextMenu
+  label: onMouseDown
+  to_state: Ready
+- from_state: EditLabel
+  label: onKeyDown
+  to_state: Selected2
+- from_state: EditLabel
+  label: onMouseDown
+  to_state: Ready
+- from_state: Move
+  label: onMouseUp
+  to_state: Selected2
+- from_state: Ready
+  label: onMouseDown
+  to_state: Selected1
+- from_state: Selected1
+  label: onMouseMove
+  to_state: Move
+- from_state: Selected1
+  label: onMouseUp
+  to_state: Selected2
+- from_state: Selected2
+  label: onKeyDown
+  to_state: Ready
+- from_state: Selected2
+  label: onMouseDown
+  to_state: Ready
+- from_state: Selected2
+  label: onMouseDown
+  to_state: Selected3
+- from_state: Selected3
+  label: onMouseMove
+  to_state: Move
+- from_state: Selected3
+  label: onMouseUp
+  to_state: ContextMenu
+- from_state: Start
+  label: start
+  to_state: Ready
--- a/docs/networking/stream.png
+++ b/docs/networking/stream.png
--- a/docs/networking/stream.yml
+++ b/docs/networking/stream.yml
@ -0,0 +1,42 @@
+finite_state_machine_id: 20
+name: stream_fsm
+states:
+- id: 4
+  label: Connecting
+  x: 344
+  y: 312
+- id: 5
+  label: Selecting
+  x: 311
+  y: 23
+- id: 1
+  label: Ready
+  x: 36
+  y: 28
+- id: 3
+  label: Connected
+  x: 55
+  y: 317
+- id: 2
+  label: Start
+  x: 43
+  y: -188
+transitions:
+- from_state: Ready
+  label: onNewStream
+  to_state: Selecting
+- from_state: Start
+  label: start
+  to_state: Ready
+- from_state: Connected
+  label: start
+  to_state: Ready
+- from_state: Connecting
+  label: onMouseUp
+  to_state: Ready
+- from_state: Connecting
+  label: onMouseUp
+  to_state: Connected
+- from_state: Selecting
+  label: onMouseUp
+  to_state: Connecting
--- a/docs/networking/test.yml
+++ b/docs/networking/test.yml
@ -0,0 +1,50 @@
+diagram_id: 69
+finite_state_machine_id: 23
+name: diagram
+states:
+- id: 1
+  label: Disabled
+  x: 895
+  y: 344
+- id: 4
+  label: Loading
+  x: 524
+  y: 710
+- id: 5
+  label: Ready
+  x: 722
+  y: 509
+- id: 6
+  label: Reporting
+  x: 926
+  y: 721
+- id: 3
+  label: Running
+  x: 720
+  y: 922
+- id: 2
+  label: Start
+  x: 702
+  y: 186
+transitions:
+- from_state: Disabled
+  label: onEnableTest
+  to_state: Ready
+- from_state: Loading
+  label: start
+  to_state: Running
+- from_state: Ready
+  label: onDisableTest
+  to_state: Disabled
+- from_state: Ready
+  label: start
+  to_state: Loading
+- from_state: Reporting
+  label: start
+  to_state: Loading
+- from_state: Running
+  label: onTestCompleted
+  to_state: Reporting
+- from_state: Start
+  label: start
+  to_state: Disabled
--- a/docs/networking/time.png
+++ b/docs/networking/time.png
--- a/docs/networking/time.yml
+++ b/docs/networking/time.yml
@ -0,0 +1,37 @@
+finite_state_machine_id: 8
+name: time_fsm
+states:
+- id: 1
+  label: Present
+  x: 256
+  y: 123
+- id: 2
+  label: Start
+  x: 245
+  y: -161
+- id: 3
+  label: Past
+  x: -115
+  y: 129
+transitions:
+- from_state: Past
+  label: onRedo
+  to_state: Present
+- from_state: Past
+  label: onMouseWheel
+  to_state: Present
+- from_state: Past
+  label: onKeyDown
+  to_state: Present
+- from_state: Start
+  label: start
+  to_state: Present
+- from_state: Present
+  label: onUndo
+  to_state: Past
+- from_state: Present
+  label: onMouseWheel
+  to_state: Past
+- from_state: Present
+  label: onKeyDown
+  to_state: Past
--- a/docs/networking/toolbox.png
+++ b/docs/networking/toolbox.png
--- a/docs/networking/toolbox.yml
+++ b/docs/networking/toolbox.yml
@ -0,0 +1,98 @@
+finite_state_machine_id: 14
+name: toolbox_fsm
+states:
+- id: 9
+  label: Disabled
+  x: 885
+  y: 141
+- id: 7
+  label: OffScreen
+  x: 1140
+  y: 217
+- id: 1
+  label: Selected
+  x: 1180
+  y: 959
+- id: 2
+  label: Move
+  x: 1409
+  y: 741
+- id: 3
+  label: Ready
+  x: 892
+  y: 429
+- id: 4
+  label: Scrolling
+  x: 567
+  y: 431
+- id: 5
+  label: Selecting
+  x: 888
+  y: 710
+- id: 6
+  label: Dropping
+  x: 1358
+  y: 431
+- id: 8
+  label: Start
+  x: 672
+  y: 196
+- id: 10
+  label: OffScreen2
+  x: 1115
+  y: -12
+transitions:
+- from_state: Ready
+  label: onDisable
+  to_state: Disabled
+- from_state: OffScreen2
+  label: onToggleToolbox
+  to_state: Disabled
+- from_state: OffScreen2
+  label: onEnable
+  to_state: OffScreen
+- from_state: Ready
+  label: onToggleToolbox
+  to_state: OffScreen
+- from_state: Selecting
+  label: onMouseDown
+  to_state: Selected
+- from_state: Selected
+  label: onMouseMove
+  to_state: Move
+- from_state: Selecting
+  label: onMouseDown
+  to_state: Ready
+- from_state: Selected
+  label: onMouseUp
+  to_state: Ready
+- from_state: Dropping
+  label: start
+  to_state: Ready
+- from_state: Start
+  label: start
+  to_state: Ready
+- from_state: Scrolling
+  label: onMouseWheel
+  to_state: Ready
+- from_state: OffScreen
+  label: onToggleToolbox
+  to_state: Ready
+- from_state: Disabled
+  label: onEnable
+  to_state: Ready
+- from_state: Ready
+  label: onMouseWheel
+  to_state: Scrolling
+- from_state: Ready
+  label: onMouseDown
+  to_state: Selecting
+- from_state: Move
+  label: onMouseUp
+  to_state: Dropping
+- from_state: OffScreen
+  label: onDisable
+  to_state: OffScreen2
+- from_state: Disabled
+  label: onToggleToolbox
+  to_state: OffScreen2
--- a/docs/networking/view.png
+++ b/docs/networking/view.png
--- a/docs/networking/view.yml
+++ b/docs/networking/view.yml
@ -0,0 +1,45 @@
+finite_state_machine_id: 2
+name: view_fsm
+states:
+- id: 1
+  label: Start
+  x: 498
+  y: 175
+- id: 2
+  label: Ready
+  x: 506
+  y: 395
+- id: 3
+  label: Scale
+  x: 310
+  y: 626
+- id: 4
+  label: Pan
+  x: 741
+  y: 631
+- id: 5
+  label: Pressed
+  x: 739
+  y: 392
+transitions:
+- from_state: Scale
+  label: onMouseWheel
+  to_state: Ready
+- from_state: Start
+  label: start
+  to_state: Ready
+- from_state: Ready
+  label: onMouseWheel
+  to_state: Scale
+- from_state: Ready
+  label: onMouseDown
+  to_state: Pressed
+- from_state: Pressed
+  label: onMouseMove
+  to_state: Pan
+- from_state: Pressed
+  label: onMouseUp
+  to_state: Ready
+- from_state: Pan
+  label: onMouseUp
+  to_state: Ready