CC Applications

Construction and Commisioning (CC) web applications developed for the Project Portal. This repo is a monorepo using Turbo and PNPM. Applications are developed using React, Typescript and Vite.

For a overview over status on planned and implemented applications, check out the overview here 🚀

Getting started 🚀

To install the dependencies required to run the project, run pnpm first-time-setup. You can then run one of the apps using one of the following commands:

pnpm serve <appname> # run app
pnpm serve:local <appname> # run app pointing to local api
pnpm build # Build monorepo in parallel 🚨 NB: Sometimes fails due to internal package dependencies
pnpm ci:build # Build sequentially

Hot module replacement is supported when using the watch command

🛡️ In order to login to the apps you need to authenticate using an Equinor account with access to a valid context/project in ProCoSys.

Developing Workspace

In this project we heavily rely on @equinor/workspace-fusion. The best way to develop this package is by symlinking the package locally and make changes that are reflected directly in the app you are working on. To symlink the package locally run this command in the cc-components folder pnpm link:workspace. This will create a subfolder in cc-components called workspace. This is a git submodule so remember that this is a git repository. The workspace folder is not a part of the cc-components folder but its rather a local copy of the fusion-workspace repository so pushing, pulling, pull requests etc still apply. When you are done using the package locally run the command pnpm unlink:workspace to unlink the package.

Contributing ⚒️

Contributing, check out our contributing guide

Issues ✨

To submit an issue, use one of the predefined issue types in Github Issues. Be sure to give good explanation and context in the issue description.

Submitted issues will be prioritized and followed up in our Github Projects.

Project structure

For project structure and development we use NX' recommendations. In general, we want to place every util, component, business logic in a library, and keep the application clean. Read more about it here.

[!TIP] Download the NX extension in VSCode to get some better support for when creating a new library or app.

The following snippet provides a brief overview of how application code is structured within the repo.

...
+-- github-action # Scripts for Github Actions
+-- apps # Configs for the different apps
|    +-- <appname>
|        +-- app.config.js # Configuration for (remote) test env
|        +-- app.config.local.js # Configuration for local env
+-- libs
|    +-- shared # Components and functionality shared between apps
|    +-- <appname>app # The code for the application
|    +-- <appname>shared # Code shared between the app and sidesheet
|    +-- <appname>sidesheet # The code for the sidesheet
+-- widgets # Code for stand-alone widgets used in the apps
...

Project organization

This project contains different apps, all related to Construction and Commission, except Scope Change Request. All the code that belongs to the apps can be found in the folders apps and libs. All the apps are located in both apps and libs.

Each app in apps only contains one file in src, main.tsx. This is the root-file for the app and contains the minimum of code, and are linked to the corresponding app in libs.

libs contains all the configurations, business logic and UI to each app.

In addition, common code that are used across multiple apps should be put inside the shared or sharedcomponents library. If it's a shared function that is calculating something or anything similar, then put it in shared, but if it's a component that is beeing used in multiple apps then put it in sharedcomponents, e.g. SidesheetSkeleton that is beeing used in multiple apps when loading the sidesheet.

Note: sharedcomponents was created a long time after shared, so sharedcomponents is not well updated and does only contain a few shared components at this time. Please keep placing shared resources in the correct folders.

App structure

This chapter only refers to the libs folder.

Each app has three different folders. The naming convention for the three folders are <appname>app, <appname>shared and <appname>sidesheet, e.g. handoverapp, handovershared and handoversidesheet.

The app folder contains all the configurations, business logic and UI to the app, except the things that are related to the sidesheet.

The shared folder contains all shared code/resources that are used in both app and sidesheet. This will typically be different types and maybe some styling.

The sidesheet folder contains all the business logic and UI for the sidesheet.

App config

All the apps are build up by the same components and configuration options. These options can be found in \libs\<appname>app\src\lib\config\workspaceConfig.tsx.

All the configuration options every app uses is filterOptions, gridOptions, gardenOptions, statusBarOptions, sidesheetOptions, powerBiOptions and workspaceOptions. Without the filterOptions you won't see any filters, without gridOptions you won't see any table, etc.

CI/CD ⚙️

Check out our development workflow here

[!IMPORTANT]
Changes merged with main will be built and deployed to production without any additional approval steps.

We continously build, test and verify all PRs submitted to GitHub.

Our applications are hosted in Fusion. Most of our apps are bootstrapped into the Fusion Project Portal. We have configured CI/CD pipelines to automatically deploy our app bundles to the Fusion app management api whenever there is a change in the code.

We have made github actions pipelines relying on TS code written in our repository. This code is being transpiled on the fly to avoid the hassle of uploading bundled js. The pipelines are located in the ./github/workflows folder

The following environments are availible:

• 🧪 Test environment
• 🏭 Production environment

The following manual deployment actions are availible:

• Manual deployment to test
• Manual deployment to production

Creating new apps 🚀

1. Run the following action to create and register the app with the fusion portal.
2. Create the app locally in CC-components. Run the following command pnpm new:app or pnpm new:report
3. To deploy the app to test, run this action
4. Follow the guide to onboard the app to the project portal. HMR does not work. To apply changes stop the server and run pnpm serve <app> HMR is disabled due to an error in dependency resolution resulting in massive bundle sizes

Rolling Back Changes

When there are bugs in production and you want production to be stable while you fix the issue. Follow these steps:

1. Create a New Branch: This branch will be based on the current state of your main branch.

   git checkout -b rollback-branch

2. Restore Code: Use git restore to revert the codebase to the state before the last commit or to a specific commit if needed.

   # Roll back to the state before the last commit
   git restore . --source=HEAD^
   
   # Roll back to a specific commit
   # git restore . --source=<commit-hash>

3. Commit the Rollback: After restoring, commit the changes to the rollback branch.

   git add .
   git commit -m "Rollback to previous stable state"

4. Push the Changes: Push the rollback branch to the remote repository.

   git push origin rollback-branch

5. Deploy to test Run this action. Verify the deployment before deploying to production

6. Deploy to production Run this action

[!IMPORTANT] Remember to inform other team members as any changes merged to main after this will overwrite your deployment.

Environment variables

We have some app configuration files in the apps/** folder. These are for local development. The permissions for modifying environment variables are given to personal accounts or service principals. We do have a service principal for deployment, but editing environment variables are done manually by developers.

• CI
• ~FQA~ (Not in use for us)
• FPRD

Onboarding new apps 🔩

Apps has to be onboarded onto a context in order to be availible for end users. Use the Onboard app to Fusion Project Portal to onboard an app to a new context. Context ids can be found by selecting the context in the portal, then copying the GUID in the url or by using the Fusion API.

[!NOTE]
Context ids vary from different environments (they are different in test and prod)

Hosting environments (subject to change)

• Fusion Project Portal
• Fusion Classic (Not here yet)
• Johan Castberg portal

Fusion framework

They way we bundle our applications makes it so that they can be used in any Fusion Portal. By utilzing the Fusion Framework we allow for communication between the portal and the application. Our applications do not have an index.html but rather exposes a mount function that the portal can call when dynamically importing our bundle. You can read more about the fusion framework here

Updating package dependencies

To update all package dependencies, use the command pnpm run bump-deps to open the interactive pnpm package update propt in the terminal. Use pnpm run compile to compile all packages/apps in the repo.

Service message

Link to dev/test.
Link to prod.

1. Navigate to the correct link above.
2. Click on "+ New service message".
3. Fill out all fields.
4. We don't have permission to publish service messages in Portal (Fusion Portal). We have only permission to publish service messages in the apps. Choose which apps to publish the message to.
5. To publish the message, press the floppy disk icon in the top right corner.

The service message will look like this