onboarding.md

Our Javascript Application Architecture & Principles

Welcome and we are happy to have you as our new team member!

This document describes the architectural goals and principles we’re trying to achieve as a team with respect to the project's codebase we develop and maintain. We hope it will help you to quickly get set up and become a valuable contributor.

Your IDE

• Use eslint & prettier to enforce consistent coding style

Principles

• KISS (keep it stupid simple) - will help to quickly onboard new developers & scale up the team
• Ability to work simultaneously & efficiently with multiple projects & services
• Increase reusability - abstract components into NPM packages
• Clear, standardized production and debugging log messages
• Maintain project / service documentation in .md files
• Multi tenant - assume services will be used by more than one tenant - maintain separate tenant environment configuration files
• Secure - leverage Secret Manager service to store sensitive credentials & service keys
• Public - when possible, without compromising security or proprietary information - the goal is to make our NPM packages public

Infrastructure & Technology Stack

We host with Google Cloud. Upon onboarding you should receive your Google account credentials, which will help you with accessing the Google Cloud Console.

Most of our project use Firebase services, especialy:

• Firebase Auth
• Firebase Firestore realtime updates
• Firebase Storage
• Firebase Functions triggers
• Firebase Hosting
• Firebase Analytics
• Firebase Extensions - like Trigger Email

We build frontend interfaces using VUE application framework. You should get familiar with documentation links.

• Docker - to automate deployments
• Google Data Studio - to visualize data

VUE applications

• Maintain simple, standard, out of the box, codebase, derived from default vue create project folder structure
• Leverage VueX store, Vuex Modules and VueX mappers as main application shared state management tool

VUE templates

• Maintain short & simple VUE file templates by abstracting script logic out of the .vue files by leveraging VueX mappers

VueX actions

• Use Promises with try {} catch (e) {} and return resolve() or reject() to handle asynchronous actions. Other collaborators will safely assume that every VueX action is always a Promise. And that will it log any important console messages or errors in a way that will identify source of the log message by leveraging common bracket format: [ file ]: message.

• We favor await statement, over .then(), .catch() to sequentially describe VueX action tasks.

If your VueX action is longer than say 60 - 100 lines of code, you probably need to break it down into several files. The goal is to save time on analyzing and debugging your VueX actions by another developer. The main VueX action file should be simple to understand without a need of endlesly scroplling through hundreds lines of code. The same applies to cloud functions code.

Due to code length limitation for single file we usually keep VueX state, getters and mutations each in a dedicated file, but break down actions into multiple files.

/**
* example VueX action template
*/
export default ({ commit, dispatch }, object) =>
  new Promise(async (resolve, reject) => {
    try {
      if (condition) throw Error("error message")
 
      [ … ]
 
      console.log("[ filename ]: success!")

      return resolve()
   } catch (e) {
     console.error("[ filename ]:", e)
     return reject()
   }
 })