Manual Reference Source

General Overview of the Project

The project is divided into three directories:

  • app regrouping the backend of the solution.
  • front regrouping the frontend of the solution.
  • tests regrouping the tests of the solution.

Backend

The directory is subdivised into:

  • app.js: the main entry point of the application.
  • mappings: the ElasticSearch mappings of the solution.
  • settings: the ElasticSearch settings for each mapping.
  • config: the general config of the solution (production, development, test).
  • initializations: all the API routes needed by the backend to work.
  • logger.js: the logger of the solution (based on Winston).
  • modules: the main logic of the backend.

Modules

The modules directory is sudivised into:

  • auth: responsible for checking the authentication of a user (will s/he be a 'real' one or an API key).
  • exceptions: collection of all the exceptions that the program can throw.
  • rate_limit: a small and easy-to-use rate limiter to avoid getting DDoS when using the APIs.
  • utils: a set of utils.
  • entities: all the data models required by the program (see Data model for more details).
  • pipeline: the standardized pipeline of the program (see Pipeline for more details).

Frontend

The frontend of the solution is subdivised into:

  • common: the common utils, components shared by the front-office & the back-office.
  • backoffice: the pages / components of the back-office.
  • frontoffice: the pages / components of the front-office.

Common

Common has multiple directories:

  • api: everything related to backend discussion: routes used to call the backend, fetching functions, and messages used for mutations in Vuex.
  • components: every reusable Vue.js components used throughout the application.
  • mixins : every Vue.js mixins used throughout the application.
  • store: the Vuex's store.
  • style: CSS templates of the application (back-office & front-office).
  • utils: couples of utility functions to help you build things faster.

Front-office & Back-office folders

  • components: every reusable Vue.js components only used for the front-office/back-office (it is the case for the header, navbar, footer of the application).
  • fonts: custom fonts that are copied to the public folder to be served and used (for custom website based on customers' graphic recommendations).
  • imgs: pictures, logos, ... used in the front-office/back-office.
  • pages: pages used in the front-office (deposit, publication view, and so on).

Backend architecture

Entities

PolarisOS is composed of an ensemble of entities (which can be viewed as collections / tables in standard databases). Each entity subclassed the so-called odm which is responsible for creation / reads / updates / deletions (CRUD) in single or bulk mode. The description of the odm lies in app/modules/entities/odm.js. Please refer to this file for a complete description of the class.

Each entity is composed of:

  1. A subclass of ODM.
  2. A models directory where the mode (and pipeline) of the entity is expressed.
  3. A controllers directory where custom controllers for each entity can be expressed.
  4. A routes directory where custom routes for each entity cas be expressed.

By default, each entity got the following routes (expressed in app/modules/utils/router.js) and features:

  • api/public/v{X}/{entity_name}s: retrieve all documents for this entity with the scroll API of ElasticSearch.
  • api/public/v{X}/{entity_name}s/{projection} : retrieve all documents for this entity with the scroll API of ElasticSearch, but restrict the_sourceparameters to what is passed toprojection` (separated by a comma).
  • `api/public/v{X}/{entity_name}s/{projection}/{population} : retrieve all documents for this entity with the scroll API of ElasticSearch, with a custom projection (can be skipped by leaving the field blank) and using custom population parameters. See the Population & Performance section for more details on population.

How to deploy the solution?

Deploy to develop with PolarisOS

Every command is run in the root directory of the project (where the package.json is). Every path are relative to this root directory.

Prerequisites

  • Elasticsearch 5.2
  • Node.js 8.9.x (LTS)
  • Gulp (latest version, should be install after Node.js using npm install -g gulp)
  • Minio 2018-04 and onwards (if you plan to host files along with metadata)
  • Grobid 0.5.x (if you plan to automatically analyze PDFs to extract metadata)

NB: We only support the latest LTS release of Node.js, but we know that the system works on 7.10 and onwards. We do not provide any support for those versions, though.

Change the configuration files

Configuration files are located in app/config. If you plan to have custom installations for both components, we advise you to change the related fields in app/config/all.js.

You need to check that the index\___prefix in app/config/all.js is set to msw before doing anything.

Create the required indices

PolarisOS needs to create indices into ElasticSearch database. To do so run the following command

node --harmony create_indices.js --create

Import the sample data

We provide sample data in an archive that you can import to bootstrap the platform.

Run the platform

In development mode, you should first build the static files then run the Node.js server.

Build the static files:

gulp default

Run the server:

npm run watch

In watch mode, any changes to files, automatically re-run the server.

Deploy PolarisOS in production

You should refer to the Git repository with the Docker configuration to do so.

Code of Conduct

Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Examples of behavior that contributes to creating a positive environment include:

  • Using welcoming and inclusive language
  • Being respectful of differing viewpoints and experiences
  • Gracefully accepting constructive criticism
  • Focusing on what is best for the community
  • Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

  • The use of sexualized language or imagery and unwelcome sexual attention or advances
  • Trolling, insulting/derogatory comments, and personal or political attacks
  • Public or private harassment
  • Publishing others' private information, such as a physical or electronic address, without explicit permission
  • Other conduct which could reasonably be considered inappropriate in a professional setting

Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at contact@mysciencework.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at http://contributor-covenant.org/version/1/4

Contributing to PolarisOS

:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code.

The following is a set of guidelines for contributing to PolarisOS. These are just guidelines, not rules, use your best judgment and feel free to propose changes to this document in a pull request.

Issues

Issues are created here.

How to Contribute in Issues

TBA

Asking for General Help

TBA

Submitting a Bug Report

TBA

Triaging a Bug Report

TBA

Resolving a Bug Report

TBA

Pull Requests

Pull Requests are the way concrete changes are made to the code, documentation, dependencies, and tools contained in the MyScienceWork/PolarisOS repository.

TBA

Style Guides

TBA