Architecture

Layer View

Overview

All the code described here can run on the Web browser. This code can be initially served from a Web server. The system can fetch data updates from remote http-based endpoints.

It can also optionally make updates onto the Web browser's screen area, via tools that provide high-fidelity access to the W3C DOM and HTML. CSS files can be pulled in as well by the Web page that requires this system. They will work as expected, but are orthogonal to this system.

Advantages

1. Vibrashank provides a minimal solution to the architectural problem of building a data-flow-based Web app, and by extension due to its use of React, iOS and Android native apps as well.
2. Vibrashank supports a data-flow architecture by not changing the view unless the application data (including the user interface state) changes.
3. Vibrashank works well with React by:
   1. Offering an avenue that is orthogonal to React for writes to the application data, so that for example writes to React component props from within the prop-supporting component are not necessary to change application state.
   2. Not touching the internals of React (or Reagent).
4. Vibrashank supports encapsulation by only allowing a given component access to the application data that belongs to a given component.
5. Vibrashank supports data transformation of asynchronously-received payloads (such as server responses) in the simplest way possible: It uses "channels" from CSP (like Go blocks), and handles ordering of transformation operations via registration of pipeable transform modules to data update types.
6. Vibrashank's use of a simple Cursor layer for the application data allows the clean addition of Demand Driven APIs.

Detail

A global, static class that is a Reagent component, Vibrashank, provides all the framework resources.

This static class, the Vibrashank component, owns a single cursor that it offers the following getters and setters to (in pseudo-code, as are all the code references here):

• .data.get([some-cursor-path], [some-component-instance])
• .data.set([some-cursor-path], [some-value], [some-component-instance], [some-update-type] /* optional */
• .fetch([some endpoint], { [some-cursor-path], /*optional*/, [some-component-instance] /* required if the preceeding parameter was supplied */, [some-update-type] /*optional*/ } /* optional */ )

A Vibrashank App (the "App") is entered in hiccup format as a child of the Vibrashank component.

A list of cursor paths to the global cursor is provided to Vibrashank (the Vibrashank component) as a React 'prop' of type Array, called appProps.

Sequence View

Initialization

At initialization time of the Vibrashank app, the Vibrashank component dereferences all the values of the various cursor locations specified in appProps, initializes its child, the App, with these values.

Run-Time

Local Get-Set

Anytime an App or App sub-component wishes to get the application data (including ui state, if any), it uses Vibrashank.data.get. Vibrashank will throw an error if the data does not have a parent named with the same React displayName in lowercase as the calling component and does not have itself its own name as such. Vibrashank enforces this by requiring a valid React/Reagent component as a parameter to get, and checking its displayName property, as well as (if possible) verifying that this component is a child of itself.

Anytime an App or App sub-component wishes to update the application data (including ui state, if any), it uses Vibrashank.data.set, with the same encapsulation constraints described above. When a successful Vibrashank.data.set call is made, the Vibrashank component calls React .forceUpdate on itself, triggering the whole app to re-render. A set call may optionally be accompanied by an update type name, in which case any Data Transformer modules that are registered to that update type name will get a chance to transform the data before it is set into the cursor, in the order that they were registered at initialization time.

Data Transformation

Data transformation is done via Data Transformation modules. These can be any code at all that accepts a single plain object input and return either null or a plain object output. They are executed by the Vibrashank.set method before that method actually sets the data into the global cursor, in the order that they are registered in. The Data Transformers are dependencies of the core Vibrashank React component listed above, and are specified to it in a React 'props' array in the order in which they are to execute should any of them register to the same update type names.

Fetch

fetch works the same as set, except that it additionally expects to set the data after it is received asynchronously.