Architecture

Introduction

SOAJS comes with the following packages:

Package	Description
SOAJS	Framework that you will use to develop your services.
Composer	Advanced Service/Daemon Generating Component that forces standardization of code and Layer isolation: REST - BL - Model
soajs.controller	SOAJS gateway service used as an entry point and forwards requests to designated services.
soajs.oauth	Security service, can be used to protect your services using oAuth 2.0
soajs.urac	User Registration and Access Control, can be used to handle and manage user accounts per tenant.
soajs.examples	Examples Package, contains 4 examples going from basic service example to fully advanced service example.
soajs.dashboard	This is the admin dashboard for soajs, enables you to configure and manage your services using a UI.
soajs.proxy	This Package, provides the ability to communicate with services deployed in other environments while working in the Operate Pillar of the Dashboard UI interface.
GCS	Generic Content Service Generator with UI Module.

Basic Service

Building a basic SOAJS service requires only two of the above mentioned packages: Framework and API Gateway.

You need the framework to build your service and you need the controller so it can forward the requests to your service.

This scenario is explained in depth in Get Started / Example 01.

When the request reaches your service, SOAJS framework captures the request first, executes the needed features based on how you configured soajs framework for this service and throws an error or hands over the request to your service business logic.

Securing a Service with oAuth

This is exactly like the previous basic service example but with oauth turned on.

This scenario is explained in depth in Get Get Started Started / Example 02.

If you attempt to directly hit the api of either Example 02 without providing an access_token, the request will be rejected.

You will need to request a token from the oauth service first, and provide it in the consecutive requests to Example 02 and 04 services.

To configure your service to be protected by oauth, set the property oauth to true.

Click Here to see the list of properties a service can use when you create it with SOAJS.

Data Layer

The data layer of soajs framework is built on top of MongoDB and uses two databases: CORE_PROVISION & CORE_SESSION

CORE_PROVISION

Collection Name	Description
environment	List of environments and their IP addresses matching registry configuration.
tenants	List of available tenants and their applications and keys information.
products	List of available products and their packages along with the ACL permissions.
oauth_users	List of oAuth user accounts related to tenants.
oauth_tokens	List of tokens related to oAuth users accounts.
services	List of Services installed.
daemons	List of Daemons installed.
daemon_grpconf	List of all Daemon Configurations.
hosts	List of deployed services & daemons in all environments. ( Manual Deployment Only )
fs.files	List of all certificates used by docker.
gc	List of all generic content schemas created by the content-builder.

CORE_SESSION

Collection Name	Description
sessions	List of sessions with full details on requests made by tenants, containing cookies, session information, api requested, key provided, passed parameters ...

Handling a Request

When a request arrives to your service, it goes through the framework first then your business logic then it goes back to the framework before returning.

The first entry to the framework, SOAJS alters the data as configured by the constructor parameters and adds the tools that SOAJS offers, SOAJS also talk to the data layer to check the key provided and the permissions and load the provisioned data based on the current running environment as configured in the Registry.

The second time the framework is used which is before returning the response, soajs formulates a unified and valid REST response before returning this response.