iqo2-api v2.0.15

Robonaut API

Docs

• Codebase
  • Technologies
  • Folder Structure
  • Code Style
• First time setup
• Running the app locally

Codebase

Technologies

Here is a list of all the big technologies we use:

• TypeScript: Type-safe JavaScript
• KOA: Next generation web framework for node.js
• MySQL: The World's Most Used Open Source Relational Database

Folder structure

├── README.md                                  # README.md
├── docker                                     # Docker configuration
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── entrypoint.sh
├── nodemon.json                               # Nodemon development server configuration
├── package-lock.json
├── package.json
├── src
│   ├── __tests__                              # Base server tests
│   ├── api                                    # All things API related
│   │   ├── __tests__                          # API tests
│   │   ├── router.ts                          # API http router
│   │   └── server.ts                          # API server based on base server
│   ├── config.ts                              # Env based config 
│   ├── constants.ts                           # Application wide constants 
│   ├── index.ts                               # Main entry point 
│   ├── log.ts                                 # Log module 
│   └── initServer.ts                          # Creates a koa http server
│   └── typings.ts                             # Typescript typings for this project
└── tsconfig.json                              # Typescript configuration

Code Style

We use Prettier on-save or on-commit, which means you can write code in whatever style you want and it will be automatically formatted according to the common style.

ESLint

On pre-commit hook, all files are checked using eslint. The configuration can be found in .eslintrc.js. It checks all js/ts files and should work out of the box.

You can run the linter manually for the codebase using

npm run lint -> simply run the linter and output the results

VSCode

If you use Visual Studio Code, you can use the following configuration

{
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": false,
  "[javascript]": {
    "editor.formatOnSave": true
  },
  "[typescript]": {
    "editor.formatOnSave": true
  },
  "[typescriptreact]": {
    "editor.formatOnSave": true
  },
}

Rules

• All new .ts files must be statically typed
• No files can have linting errors
• All files must be tested: CI will fail your build if you do not need the coverage treshold (see package.json)
• No console.logs in any file: Never commit a file that contains a console.log

Typings

This project is typed with Typescript. For typings that are not part of the type generator, follow these guidelines:

• make sure that the TS build step clears on commit. You can run this locally with npm run typecheck (or npm run typecheck -- --watch if you want to continuously check). It's good practice to run this regularly, as VSCode will generally not look app-wide for errors.
• prefer creating an interface in stead of a type when creating your very own type from scratch
• prefer creating a type in stead of an interface when making an alias that is just a merge/extend/union of other types
• make a typings.ts file on component/view/module level and export all your type info from there. This centralizes everything nicely and creates a predictable location to look for type info for that specific section of the app
• you can locally make a union or composition of an exported type inline (eg. ColorType | string[] or Record<ColorType, string>) but if you use it more than once, or it becomes a behemoth, consider adding an alias for the construct to the typings.ts file.

First time setup

The first step to running this API locally is downloading the code by cloning the repository:

$ git clone git@github.com:iqo2/api.git

Prerequisites

• Git
• Node.js > 12
• Docker

Installation

1. Install npm dependencies

$ npm install

Running the server locally

Develop

$ npm start

API

$ SERVER_FLAVOR=api npm start

Admin

$ SERVER_FLAVOR=admin npm start

Test

$ npm t