# Project structure

# Introduction

This project is a mono-repository with the following directories:

• admin: The admin dashboard of the platform
• backend: The server of the platform
• frontend: The client of the platform
• common: The common files
• docs: The documentation of the platform

# Technologies

To build this platform, we are using:

• Nuxt.js (opens new window) - Framework used to create a Vue.js application using SSR.
• Vue.js (opens new window) - Progressive framework for building user interfaces.
• Vuex (opens new window) - State management for Vue.js.
• nuxt-i18n (opens new window) - A vue-i18n (opens new window) integration, automatic routes generation prefixed with locale code, routes translation, SEO, lazy-load, auto-detect language and other features.
• Stylus (opens new window) - Style language.
• Pug (opens new window) - Template language.
• Express (opens new window) - Fast, unopinionated, minimalist web framework for Node.js.
• GraphQL (opens new window) - A query language.
• Apollo GraphQL (opens new window) - A GraphQL implementation.
• AJV (opens new window) - A JSON schema validator.
• ESLint (opens new window) - Lint for JavaScript.
• dotenv-safe (opens new window) - Ensures that all necessary environment variables are defined.
• Element UI (opens new window) - A Desktop UI Library.
• Nightwatch.js (opens new window) - e2e testing.
• Puppeteer (opens new window) - Headless Chrome Node.js API for useful tasks (e.g.: PDF generation)
• Mailgun (opens new window) - An email service.
• Mangopay (opens new window) - Payment service provider.
• Lemonway (opens new window) - Payment service provider.
• Yousign (opens new window) - Electronic signature service.
• Jenkins (opens new window) - Automated deployment with custom pipeline.
• Clever Cloud (opens new window) - Hosting service.
• And others...

# Platform driven by the environment

C4$hM4chin3 is a white-label platform built for PepperState and Collecticity. Anything being platform-specific (theme, some features, etc.) is driven by the environment variable PLATFORM_NAME

Accepted values:

• PepperState
• Collecticity

The same way, the environment variable PAYMENT_SERVICE_PROVIDER defines which service is used.

Accepted values:

• MANGOPAY
• LEMONWAY

# Static files

Files specific to a platform like logos can be served as static files. Put the files in the folder common/$PLATFORM_NAME/static.

A file common/pepperstate/static/logo.svg will then be served at $HOST/logo.svg.

# Themes

For each platform, there is a theme located in the folder common/$PLATFORM_NAME/theme.

This is were colors, fonts, breakpoints, etc. are defined. Import the file common/getTheme.js to dynamically get an object with all the variables defined:

import getTheme from "common/getTheme";

const theme = getTheme(process.env.PLATFORM_NAME);
console.log(theme);
/*
output:
{
  borderRadius: {},
  breakpoints: {},
  colors: {},
  fonts: {},
  transitions: {}
}
*/

# Element UI theme for the frontend

In order to deeply stick to the platform's identity, a custom theme for Element UI is generated. This theme written in sass extends the default theme from Element UI (theme-chalk (opens new window)). The entry point of the theme is located in frontend/assets/styles/element-ui/index.scss.

Element UI has a set of overridable variables. The list of these variables is in this file (opens new window). Our custom variables are located in frontend/assets/styles/element-ui/custom/variables.scss. As the original theme, variables are prefixed by --.

We use a generated css file per platform so whenever the theme changes, we need to regenerate them:

cd frontend
npm run element:themes

This command uses gulp to generate a css file for each platform in the folder element-ui. The task in the gulpfile uses a custom json loader to use json files as sass variables, allowing us to fetch the right theme for the right platform. As result of the task, each css file is named after its platform name. The css file corresponding to the current platform is then dynamically imported in the nuxt.config.js.

# Objects

In addition to the original theme, css objects have been created. Objects are reusable and abstract set of styles defined using sass placeholders (opens new window). All objects are prefixed by -o- in order to be clearly identifiable.

Objects are located at frontend/assets/styles/element-ui/custom/objects/.

@import "./{PATH_TO_OBJECT}";
.-o-my-object {
  @extends -o-my-object;
}

# Adding an object

Let's assume we want to add the layout object container.

Add the placeholder in a file ~/assets/styles/element-ui/custom/objects/layout.scss

%-o-container {
  padding-left: 2rem;
  padding-right: 2rem;
}

# Using an object

@import "./{PATH_TO_OBJECT}";

.my-selector {
  @extend %-o-title-2;
}

# Mixins

# Breakpoints

The res-spec mixin have been created for media queries:

.my-selector {
  // This style will be only applied to xs devices
  @include res-spec(xs-only) {
    padding-right: 50px;
  }
}

# Components

Element UI components are written usig the BEM syntax (opens new window). They use mixins b, e, m, respectively Bloc, Element and Modifier to write their style. We chose to follow the same rules.

# Overriding a component style

To override the component el-button:

• Create a file named button in the folder ~/assets/styles/element-ui/custom/components/.
• Add this comment a the top of the file:

  // Custom style for Button
  // src: https://github.com/ElementUI/theme-chalk/blob/master/src/button.scss
  

• Import files you need, for instance variables and mixins
• Add the custom style by following the same structure of the original file:

  @include b(button) {
    // will automatically prepend with the prefix `el-`
    // custom style
  }
  

# Using theme's variables in stylus

It's possible to import JSON files as variables in stylus. A variable $platform-theme that represents the path to the current platform's theme is injected in the stylus loader so to import a JSON file, simply do:

json($platform-theme + '/colors.json')

# Deployment

A pipeline on Jenkins is triggered on every commit. The behavior is described in the file Jenkinsfile at the root of the project.

# Stages

The pipeline is separated in different stages:

• Notify: Notifies the beginning of the job in Slack and log different information.
• Build: Build each app for end-to-end tests.
• Run: Run each app for end-to-end tests.
• Test: Test each app (eslint, end-to-end in headless mode).
• Deploy: Deploy each app.
• Deploy docs: Deploy the documentation.

# Driven by the branch name

The behavior of the pipeline is driven by the branch name on which the pipeline is running, following these conditions:

# End-to-end tests

Both admin and frontend are subject to end-to-end tests. On test failure, a screenshot will be saved as an artifact in the job and the deployment be skipped.