SciForge API: Code Architecture
Video: Discussion and Examples
SciForge code is organized to enable a SOLID and DRY approach to programming the API. The flexibility to build your own plugins goes hand in hand with the flexibility of Elab, and the expectation that every instance is used differently. Existing code can be extended, over-ridden, or entirely new features built to suit the intended purposes. With the expectation that the endpoints needed for one remote application may be different than others, the folder structure helps to support organization of implemented end points by application.
A graphical representation of the intended architecture is shown below.
This architectural principle is reflected in the directory structure of the code, and in how they are used. A screenshot of the folders in the COTS elab-api repository src directory is shown below.
Layer | Folders | Discussion |
|---|---|---|
Models | types | Classes to support various API features, such as result pagination, logging, authentication. |
typeDefs | Classes matching underlying database schema, with appropriate GraphQL and Sequelize decorators. | |
Model Services | modelServices | Interfaces with requirements for various implementations in higher layers, such as repositories, timezone logic, and picklists. For simplicity, many implementations that are correctly part of the top layer are organized in sub-folders, such as repositories. |
Application Services | appServices | Classes here support the functionality in the implementation layer, and may take on a lot of forms. Timezone clock services, report and file services, resolver input model to schema model mapping (often labeled as “controllers”) are a few examples. |
Implementation (labeled Resolvers, Mutations above) | resolvers | This layer mostly has GraphQL queries and mutations, however, this layer is really where everything comes together for code implementation. As such, the infrastructure, including choice of database or other persisted data, is also considered to be a part of this layer. |
Plugin
Plugins are code that extend or change the functionalities of the COTS source.
Note in the screenshot, above, that there is a folder labeled “plugin.” In the “Getting Started” module, this was created, using git, from an independent repository.
The structure of the plugin folder is consistent with the COTS structure and architectural model.
There are 3 folders shown in the root directory. The folders “typeDefs” and “modelServices” are required. The remaining folders are used to store specific information for individual applications, such as resolvers to support a portal, or BI or warehousing tool that can consume GraphQL. The example-app folder may be copied as a starting point for any applications that custom changes via the plugin are intended to support.
The purposes of the folders are the same as described in the above table.
LabLynx personnel will create this repository from a template that is kept for this purposes, and provide access to authorized individuals. The naming convention for plugin repositories is: sciforge_<client ID>
For the client ABCD the repo is created as sciforge_abcd.
SciCloud Plugin Configuration
SciCloud is the name of the hosted services platform, including the suite of applications. SciForge is one the applications in this suite. Production and test environments reside on a server called the “SciCloud server.” When a SciForge plugin exists, the server needs to be configured to utilize this plugin.
In the development environment, no special configuration is required. The developer, when working on the API, simply pulls the correct plugin repository, per instructions in the “Getting Started” modules.
The production and test environments need to be made aware that a plugin should be utilized, and where the plugin is located. The automated features of the SciCloud platform will then automatically pull the latest changes from the plugin into the production and test environments.
The configuration variables that need to be set for production and test are:
In production the branch is always left as master. In the test environment, this is altered once a test branch is created.