Home

Awesome

ExplainaBoard Web

This repository includes code for frontend and backend of the ExplainaBoard web application. The frontend is built with React and the backend uses Flask.

Contribution Guide

Schema Design

Quick Start for Developers

This step-by-step guide assumes a Linux environment. A MacOS environment will likely work similarly. For Windows users, the easiest way is to use a subsystem, for example WSL (pre-installed since Windows 10).

  1. Install node and npm

    • The recommended way is to install nvm and use nvm to manage node versions. Run nvm install to install node and npm.
  2. Install java. Verify that java is installed correctly in your environment by running java --version.

  3. Generate code for API layer

    • Run npm run gen-api-code to generate code for api layer (both server and client). Please remember to run this whenever OpenAPI definition changes.
  4. Setup dev environment for the frontend

    1. Install project dependencies npm install
    2. Install frontend dependencies npm --prefix frontend install. See FAQ when npm reports vulnerabilities.
  5. Setup dev environment for the backend

    1. Install python version >= 3.9.7 and create a venv or conda environment for this project
    2. pip install -r backend/requirements.txt -r backend/src/gen/requirements.txt
    3. Create backend/src/impl/.env to store all environment variables. An example has been provided in .env.example. Contact the dev team to get the credentials for dev and prod environments.
    4. Set up a GCP account and authenticate locally:
      • Contact the dev team to setup a GCP account with access to the dev bucket of Cloud Storage.
      • Install gcloud and then run gcloud auth application-default login to login to the user account locally. (for more information, see this guide)
      • Set project by running gcloud config set project inspired-app-eb-dev
  6. Install pre-commit hooks

    • Run npm run prepare to install the pre-commit hook via husky. The hook auto-checks both frontend and backend code before commits. Please do not skip it.
  7. Launch explainaboard

    1. Run npm run start to start the frontend and backend server concurrently.
      • Both frontend and backend can be started independently as well. Check out "More details on frontend and backend".

Important notes on local development

Deployment

More details on frontend and backend

Frontend

Backend

Project Structure

- .husky # for running pre-commit checks
- openapi
   - openapi.yaml # api specifications
   - gen_api_layer.sh # script to generate client and server code according to openapi specifications
   - swagger-codegen-config.json # config file for swagger(openapi) code gen

- frontend
   - public # static resources for frontend
   - src    # frontend code
      - clients # all clients (backend, oauth login, etc.)
         - index.ts # all generated clients are exported here
   - .eslintignore
   - .eslintrc.json
   - .prettierrc.json
   - package-lock.json # lock file for frontend dependencies
   - package.json # package config file for frontend
   - tsconfig.json # typescript config

- backend
   - templates # mustache templates to generate template code
   - requirements.txt
   - src
      - gen # template code generated with openapi, code in this folder should not be
            # modified manually
         - requirements.txt
         - explainaboard
            - __main__.py
            - controllers
            - test
            - models
            - impl # a sympolic link to the impl folder, any edition made here will
                   # "reflect" on the impl folder
      - impl # our implementation of the apis

- .gitignore
- README.md
- Dockerfile
- package.json # package config file for global dependencies and commands
- package-lock.json # lock file for global dependencies

FAQ

npm install --prefix frontend says we have x vulnerabilities

Solution: Run npm audit --prefix frontend --production. If it says 0 vulnerabilities, we are fine.

Reason: We use create react app for frontend, and the react-scripts dependency in frontend/package.json is causing these false alarms. Here's the moderator of create react app explaining why 99.9% of the vulnerability reports in react-scripts are false positives and how to fix them.

Credits/Contributing

This software was initially developed by Lyuyang Hu, Chih-Hao Wang, Pengfei Liu, and Graham Neubig, a collaborative effort of Carnegie Mellon University and Inspired Cognition Inc. We highly welcome questions, issues, and pull requests. Please get in contact through github issues above.