Customer-success-management-app NPM

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

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