# CC Applications
Construction and Commisioning (CC) web applications developed for the Project Portal. This repo is a monorepo using [Turbo](https://turbo.build/) and [PNPM](https://pnpm.io/). Applications are developed using [React](https://react.dev/), [Typescript](https://www.typescriptlang.org/) and [Vite](https://vitejs.dev/).
> For a overview over status on planned and implemented applications, check out the overview [here 🚀](https://github.com/equinor/cc-components/issues/693)
## 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:
```bash
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](https://webpack.js.org/guides/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](https://github.com/equinor/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](./CONTRIBUTING.md)
## 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](https://nx.dev/more-concepts/monorepo-nx-enterprise#using-nx-at-enterpriseshere).
> [!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.
```py
...
+-- 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> # All code for the application (config, garden, shared types, 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 is a single library named after the app, e.g. `handover`, `workorder`. The library bundles everything for that app:
- `src/lib/config/` — workspace, table, garden, sidesheet and framework configuration.
- `src/lib/shared/` — shared code/resources (types, styling) used by both the app and its sidesheet.
- `src/lib/sidesheet/` — all business logic and UI for the sidesheet.
- `src/lib/ui-garden/`, `src/lib/utils-garden/`, `src/lib/utils-statuses/` — garden view and status helpers.
### App config
All the apps are build up by the same components and configuration options. These options can be found in `\libs\<appname>\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](./CONTRIBUTING.md)
> [!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](https://project.fusion.equinor.com). We have configured CI/CD pipelines to automatically deploy our app bundles to the [Fusion app management api](https://fusion-s-portal-fprd.azurewebsites.net/swagger) 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](https://webserver-fusion-project-portal-test.radix.equinor.com/)
- [🏭 Production environment](https://project.fusion.equinor.com/)
**The following manual deployment actions are availible:**
- [Manual deployment to test](https://github.com/equinor/cc-components/actions/workflows/manual-deploy.yml)
- [Manual deployment to production](https://github.com/equinor/cc-components/actions/workflows/manual-deploy-prod.yml)
## Creating new apps 🚀
1. Run the following [action](https://github.com/equinor/cc-components/actions/workflows/create-fusion-app.yml) to create and register the app with the fusion portal.
2. Create the app locally in CC-components by copying an existing app and its `libs/<name>{app,shared,sidesheet}` libraries, then renaming the packages.
3. To deploy the app to test, run this [action](https://github.com/equinor/cc-components/actions/workflows/manual-deploy.yml)
4. Follow the [guide](https://github.com/equinor/lighthouse/blob/main/docs/project-portal/administration.md) to onboard the app to the project portal.
[HMR](https://webpack.js.org/guides/hot-module-replacement/) 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.
```sh
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.
```sh
# 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.
```sh
git add .
git commit -m "Rollback to previous stable state"
```
4. **Push the Changes:**
Push the rollback branch to the remote repository.
```sh
git push origin rollback-branch
```
5. **Deploy to test**
Run this [action](https://github.com/equinor/cc-components/actions/workflows/manual-deploy.yml). Verify the deployment before deploying to production
5. **Deploy to production**
Run this [action](https://github.com/equinor/cc-components/actions/workflows/manual-deploy-prod.yml)
> [!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](https://admin.ci.fusion-dev.net/apps)
- ~[FQA](https://admin.fqa.fusion-dev.net/apps)~ (Not in use for us)
- [FPRD](https://admin.fprd.fusion-dev.net/apps)
## 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](https://github.com/equinor/cc-components/actions/workflows/onboard-app-fpp.yml) 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](https://project.fusion.equinor.com)
- [Fusion Classic](https://fusion.equinor.com) (Not here yet)
- [Johan Castberg portal](https://jc.fusion.equinor.com)
## 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](https://github.com/equinor/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](https://equinor.github.io/fusion-framework)
## 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](https://admin.ci.fusion-dev.net/service-messages/manage).
Link to [prod](https://admin.fprd.fusion-dev.net/service-messages/manage).
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
