Architecture
- Antoine Hage (Unlicensed)
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 API 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 | SOAJS Console is the admin dashboard for soajs, enables you to configure and manage your services using a UI. |
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 GetGet 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.
Cloud Architecture Overview
The following provides an overview of how an environment built using SOAJS looks like.
| Component | Purpose |
|---|---|
| Nginx Server | Web server used as entry point to the cloud of this environment, add an extra layer of security when used with SSL certificates and upstream API traffic as well as load balances it when redirecting it to the SOAJS API Gateway. |
| SOAJS API Gateway | Previously referred to as the soajs.controller, receives traffic from Nginx and runs it against all security protocols. If the request is valid, the gateway loads all associated provisioned configuration such as tenant information, registry, logged in user information ..., attaches it to the request and forwards the request to the microservice requested. |
| Microservice | Atomic HTTP Server that contains APIs that handle forwarded traffic from the SOAJS API Gateway. The microservice can be built using the SOAJS framework, or can be built using any language and uses the SOAJS Middleware. |
