GreenForce

Monorepo for the DataHub and
Energy Origin
frontends backed by Nx and Angular.

Table of Contents

• General
• Prerequisites
• DataHub
  • Documentation
  • Getting Started
  • Development
  • Backend For Frontend (BFF)
  • Configuration
• Energy Origin
• Watt Design System
• Workspace
  • Applications
  • Libraries
  • Tools
• Scripts
• Workflows (CI/CD)
• Visual Studio Code
• Domain C4 model

General

The documentation in this README assumes the reader has a general understanding
of Nx and Angular. For beginners in these technologies, the
Core Nx Tutorial and
Angular Tour of Heroes serves as a good
introduction.

This repository is a monorepo which hosts serveral applications that all share
the same dependencies (for example, every application is running the same
version of Angular).

Note: Since this is an Nx workspace, the Nx CLI should be used
over the Angular CLI.

Prerequisites

• Volta: Manager for JavaScript command-line tools like Node.js®, Yarn and Bun.
• Bun: Alternative to Node.js® and Yarn that this repository use. Can also be installed with Volta.
• .NET SDK: Required for running and developing DataHub.

DataHub

The application is deployed to the following environments:

Documentation

Be sure to check out the additional DataHub documentation for the following
areas:

• Testing
• Mocking
• Feature Flags
• Logging with Application Insights

Getting Started

Before starting the development server, you must install localhost.crt in your list of locally trusted roots.
Run the following command as an administrator from the root of the repository (Windows):

certutil -addstore -f "Root" localhost.crt

Use the following command to serve the DataHub application locally (with request mocking):

bun dh:mock

The application utilizes request mocking for some of the requests to the
backend for frontend (BFF), but there are still
features that are not mocked. When working with those features, it might be
required to serve the BFF locally as well. To do so, run the following command
(requires some initial setup, see
Setup of BFF).

bun api:dev

Note: It is recommended to use mocking as much as possible, see
mocking.md.

Development

When it is time to add a new library, refrain from writing files manually or
copying from existing libraries. Instead, use the provided local generators
that takes care of all the manual work and avoids common pitfalls.

Note: Make sure to read the Workspace section beforehand to understand
which library type to generate. It is currently not possible to generate
libraries of type assets and styles.

To generate a new library, run the below command* and follow the instructions:

bun nx g @energinet-datahub/tools/workspace:library

While rarely needed, it is also possible to generate an entirely new domain.
Running the following command* will create a new domain with
data-access-api, feature, and shell libraries included:

bun nx g @energinet-datahub/tools/workspace:domain

Also available in Nx Console.

Best Practices$$

Take a look at our dev examples to see how to implement certain features like, and an overall best practice guide:

• Data table
• Form
• Modal
• Dropdown
• Drawer
• Description list
• Navigation

Backend For Frontend (BFF)

There is currenly only one BFF located in api-dh under apps/dh.
It is for app-dh and is using .NET 8.x.
Check the Development notes
for how to get started.

Configuration

Configuration files are located in the libs/dh/shared/assets/src/assets/configuration
folder. These local configurations have a .local filename suffix, but is
overridable by a configuration file without the suffix. For example,
dh-api-environment.local.json configures the DataHub frontend to use a local
DataHub API. To use a remote DataHub API, place a dh-api-environment.json file
in the same folder and set the remote address in the relevant property.

Energy Origin

Use the following command to serve the Energy Origin application locally (with request mocking):

bun eo:mock

Watt Design System

Contributing? Check the Watt Design System README
for developer documentation.

This is a shared UI library meant to be used by all frontend apps and it
contains basic components and functionality for speeding up app development.
It is located in libs/watt and can be imported from
@energinet-datahub/watt in other libraries.

The design system is showcased using Storybook,
and can be found here: Latest version (main)

To use components or other functionality from Watt, import as in the following
example:

import { WattButtonComponent } from '@energinet-datahub/watt/button';

Workspace

The structure of the monorepo is based on general conventions from
Nx with a few extensions. On the highest level the
workspace is separated into apps and libs, with most of the logic
placed within the libs folder. The apps should mostly be slim
containers that links to functionality implemented in libraries.

On the top level, the workspace is divided into the following folders:

Energinet-DataHub/greenforce-frontend
├── apps      # Source code for applications
├── build     # Infrastructure related to deployment
├── dist      # Output files when building artifacts
├── docs      # General documentation
├── libs      # Source code for libraries
├── scripts   # Code needed for running certain commands
└── tools     # Logic for executing or generating code

Applications

Within the apps folders resides the applications, which includes frontends,
BFF and E2E tests. These applications are prefixed with their type and further
grouped by a product root folder. Expanding the apps folder looks like this:

...
└── apps            # Source code for applications
   ├── dh           # DataHub application (product root)
   │  ├── api-dh    # - BFF for DataHub
   │  ├── app-dh    # - Frontend for DataHub
   │  └── e2e-dh    # - E2E tests for DataHub
   └── eo           # Energy Origin (product root)
      ├── app-eo    # - Frontend for Energy Origin
      └── e2e-eo    # - E2E tests for Energy Origin

In other words, all applications must follow the naming scheme
apps/<product>/<type>-<product>.

Below is an exhaustive list of permitted application types, along with their
intended purpose, folder name and which library types they are
allowed to have direct dependendies to:

Libraries

As mentioned above, libraries are where most of the logic goes. They are all
either related to a single product or shared across multiple products*.
There are many different library types which are listed further below, but they
all follow the same naming convention:

The special gf product can be used for libraries that must be shared
across multiple products.

...
└── libs                                      # Source code for libraries
   └── <product>                              # Libraries are grouped by a product root folder
      └── <domain>                            # Products can contain several domains ex. auth, core, etc.
         └── <library type>-<library name>    # Domains can contain several libraries prefixed by type
   └── watt                                   # Special product, see "Watt Design System" section

Note: Certain library types should not have a name; in that case simply omit
the -<library name> suffix.

Following is an exhaustive list of permitted library types, what they should
contain, their name and which other library* types they are allowed to
depend on:

Only
libraries of type data-access may have dependencies to apps and only apps of type
api.

Library types

Tools

This folder contains code only meant for use during development or within
workflows. Expanding it looks like this:

...
└── tools/src
   ├── executors     # Perform all sorts of actions on your code
   ├── generators    # Automate tasks using code generation
   └── <helpers>     # Various other helper tools e.g. for scripting

Executors and generators are Nx inventions; for
documentation on how to work with them, see
Use Task Executors and
Use Code Generators.

Scripts

• bun dep-graph: Generate a dependency graph for the applications in the monorepo.

Workflows (CI/CD)

The repository is using GitHub Actions workflows
for automation including CI/CD pipelines for each application.
Workflows are located in .github/workflows which currently contains the following:

• ci-orchestrator.yml - Markdown check and YAML validation, detects changes to start relevant workflows and branch policy status check.
• create-tokens.yml - Generates design tokens based on a JSON file exported from Figma.
• detect-changes.yml - Figures out what part of the codebase is affected by a change.
• dh-cd.yml: Used by DataHub for updating BFF code coverage, publishing a release, dispatching a deployment request, and dispatching a notification on failure.
• dh-ci-dotnet.yml - Verifies the ASP.NET Core Web API by building and running all tests. Used in ci-orchestrator.yml for verifying if PR merge is allowed.
• dh-ci-frontend.yml - Used by DataHub frontend for publishing a release and generating API clients. Used in ci-orchestrator.yml for verifying if PR merge is allowed.
• dh-healthchecks.yml - Runs E2E health check tests every hour against all DataHub environments.
• eo-cd.yml - Used by "Energy Origin" app.
• frontend-ci.yml - Used to build, format and lint all frontend apps. Also used for running unit, integration, component and E2E tests.
• license-check-ci.yml - Used to check for license headers in files and adding them if missing.
• production-dependencies-license-check.yml - Used for documenting used versions and licenses of production dependencies.
• watt-cd.yml - Used for publishing Watt to Chromatic and dispatching a notification on failure.
• watt-ci.yml - Used by Watt for verifying a production build can be created. Used in ci-orchestrator.yml for verifying if PR merge is allowed.

Bots are used for certain trivial tasks such as adding license headers to files,
formatting code, fixing lint errors, and generating API clients based on OpenAPI.
For this to work, bots have to use the repository secret PAT_TOKEN when pushing
changes or creating releases that trigger a workflow. Only do this for idempotent
tasks to prevent circular workflows from causing infinite workflow runs.

Visual Studio Code

It is recommended to use the Visual Studio Code
editor, as it supports the entire toolchain of this repository and has
been preconfigured with a list of recommended extensions stored in
.vscode/extensions.json. The editor will automatically prompt for installing
these extensions when the project is opened for the first time, but they can
later be found by executing the Show recommended extensions command.

Domain C4 model

In the DataHub 3 project we use the C4 model to document the high-level software design.

The domain C4 model and views are located in c4-arch-diagrams repository.

Thanks to all the people who already contributed