Customer Success Management App

This app provides access to detected insights for assets that can then be processed further in a sales team. This is part of the MaaS project, providing the internal facing side of conversations.

Development

Prerequisites

1. node.js (>=16.10)
2. yarn

IDE/VSCODE setup

• Install VS Code extension ZipFS - a zip file system (arcanis.vscode-zipfs)
• If missing imports pop up in the IDE, execute yarn dlx @yarnpkg/sdks to make the ide aware of the necessary workspace settings (more on this is available here).

Code formatting

This project uses prettier to automatically format the source code.

• Install the VS Code extension Prettier - Code formatter (esbenp.prettier-vscode)
• Activate "Prettier: Require config" in VS Code settings to avoid formatting other projects
• Activate "Editor: Format On Save" in VS Code settings to activate formatting on every save

Tailwind CSS IntelliSense and Twin

• Install the VS Code extension Tailwind CSS IntelliSense

• From your command palette select: "Preferences: Open Settings (JSON)" and add this to your settings:

  "tailwindCSS.experimental.classRegex": [
      "tw`([^`]*)", // tw`...`
      "tw=\"([^\"]*)", // <div tw="..." />
      "tw={\"([^\"}]*)", // <div tw={"..."} />
      "tw\\.\\w+`([^`]*)", // tw.xxx`...`
      "tw\\(.*?\\)`([^`]*)" // tw(Component)`...`
    ],
    "tailwindCSS.includeLanguages": {
      "typescript": "javascript",
      "typescriptreact": "javascript"
    }

Local Development

Note:

• The app requires a redis-server. The connection can be configured via config and defaults to 127.0.0.1:6379.
• In order to receive FCM messages during development the flag --serviceWorker has to be passed to the watch command and fcmConfig-config updated.
• The sync feature for the inbox relies on a redis pubsub mechanism. In order to make this work during development a tunnel to the pubsub instance is required and the inbox.pubsub-config has to be updated accordingly.

export YARN_NPM_AUTH_TOKEN=<<< your auth token >>>
yarn
yarn watch

Implementation details and constraints:

• The top-level lib-folder provides functionality for the server- and client-portion of the app. It mustn't import anything from the client-folder. There are 2 exceptions to this: types and files within client/i18n/ may be imported.
• The app is built with typescript 3.9, reactjs 17.0 and primarily uses material-ui.
• While there is a css-loader in place, styling should primarily happen with emotion and/or makeStyles (provided by material-ui)
• Low-level styling can and should use tailwindcss via the twin.macro.
• Flexbox (whether it's used via tailwindcss or material-ui) should only be used where it makes sense, but not for grid-layouts. Grid layouts should only be built with CSS Grid Layouts. Tailwindcss simplifies that quite a bit: https://tailwindcss.com/docs/grid-template-columns/#app.
• Configurable dashboards should utilize the DashboardRenderer component
• Drag-and-drop functionality should be built with react-dnd
• Forms should be built with Formik
• Data should primarily be handled via graphql. Use yarn codegen to automatically create typescript definitions
• The Seshat REST api can be used via @rest but the schema has to be manually defined by the developer in localSchema.graphql

  type RESTAsset {
    id: Long
    serialNumber: String
  }
  extend type Query {
    restAsset(id: Long): RESTAsset
  }

  const testQuery = gql`
    query TestQuery($id: Long) {
      restAsset(id: $id) @rest(type: "RESTAsset", path: "asset/{args.id}") {
        id
      }
    }
  `;

  const { data: restData } = useQuery<TestQuery>(testQuery, {
    variables: {
      id: 153325,
    },
  });

Redis schema migrations

Running migrations

Generally, this is not required for development, as a simple db flush would be sufficient.

yarn migrate

Writing migration

Migrations live within the server/migrations folder. To generate a new migration, run

yarn generate:migration hello_world

This will generate a new file within server/migrations with the name format <identifier>_<name>.ts. The identifier is constructed by the current utc time.

The migration file contains a single function named up(version, adapter). This is where your migration code goes. You should handle anything here regarding migrations (e.g. update database entries). If you return a promise, it will be awaited during migration.

To make writing migrations a bit easier, there is a migrationHelper.ts which exports commonly used helper functions.

Testing

Testing is setup with jest and @testing-library/react.

CI/CD

• Base-branches are protected and require PRs
• Tests and static code-checks are automatically run for every PR against the develop-branch and are a prerequisite for merges to the base-branch.
• The deployment is handled by ArgoCD
• Every commit to the develop-, hotfix- or release-branch (patterns: release/** hotfix/**) is going to be build and deployed to http://energy-management-dev.staging.myplant.io
• Every tag that is pushed (pre-release or release) is going to be build and deployed to http://energy-management.staging.myplant.io/

Collaboration

• The project uses the gitflow-workflow.

• Commit messages are standardized. A commit message will have the form:

  <type>[optional scope]: <description>
  [optional body]
  [optional footer]

  Few notes:

  • the description references the UserStory and a gives a short-description
  • All commmit messages may have a body (more text).
  • Any breaking change must include a text BREAKING CHANGE.
  • Other commit types as well as scopes are optional.

  Here are some examples:

  • bugfix: fix: <US-Story> short description
  • new feature: feat: <US-Story> short description