https://github.com/hochfrequenz/ahb-tabellen

AHB Tabellen - Anwendungshandbücher für Menschen
https://github.com/hochfrequenz/ahb-tabellen

ahb anwendungsha bdew energiew

Last synced: 3 months ago
JSON representation

AHB Tabellen - Anwendungshandbücher für Menschen

• Host: GitHub
• URL: https://github.com/hochfrequenz/ahb-tabellen
• Owner: Hochfrequenz
• Created: 2024-05-13T11:32:51.000Z (about 2 years ago)
• Default Branch: main
• Last Pushed: 2026-03-09T00:23:48.000Z (3 months ago)
• Last Synced: 2026-03-09T05:39:41.070Z (3 months ago)
• Topics: ahb, anwendungsha, bdew, energiew
• Language: TypeScript
• Homepage: https://ahb-tabellen.hochfrequenz.de/
• Size: 1.01 GB
• Stars: 3
• Watchers: 1
• Forks: 0
• Open Issues: 35
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

          
# AHB-Tabellen Web Application

## ℹ️ Overview

### Production

You can access the **prod** version of the application on [ahb-tabellen.hochfrequenz.de](https://ahb-tabellen.hochfrequenz.de).

### Stage

You can access the **stage** version of the application on [ahb-tabellen.stage.hochfrequenz.de](https://ahb-tabellen.stage.hochfrequenz.de).

This is our test environment where we deploy the latest changes to test them before deploying them to production.

### 🏛 Architecture

The AHB tables application follows a simple but effective architecture for processing and displaying Anwendungshandbücher (AHB) data:

1. **Data Source**: The process begins with XML files from edi@energy, which contain the official AHB specifications.

2. **Data Processing**: Our Python package `fundamend` processes these XML files, extracting and structuring the data into a SQLite database format.

3. **Web Application**: The AHB tables web application reads directly from the SQLite database to display the structured AHB information to users.

This architecture ensures data consistency and provides a reliable way to access and display AHB information.

```mermaid

flowchart TD

    A("edi@energy:

    XML files") -->|fundamend| B("SQLite Database")

    B -->|read| C("AHB-Tabellen

    web application")

```

### 📂 Project Structure

This is an API first application.

Whenever you want to change something in between frontend and backend, start by changing the [OpenAPI spec](openapi.yml) first and continue from there (`npm run ng-openapi-gen`).

```plaintext

.

├── src/

    ├── app/

        ├── core/

            └── api/              # API config files

        ├── environments/         # config files for dev/stage/prod

        ├── features/             # AHB and landingpage related views and components

        └── shared/               # global components (header, footer, logo, etc.)

    ├── assets/                   # logo, favicon, etc.

    ├── server/

        ├── controller/           # contains code to handle incoming http requests concerning AHB and FormatVersionen

        ├── infrastructure/       # contains code to manage routing of API endpoints and interact with azure blob storage

        └── repository/           # contains CRUD operations to register AHB/FormatVersionen related routers

    ├── index.html                # entry point for the angular web application

    ├── main.ts                   # bootstraps the angular web application

    ├── server.ts                 # sets up backend server

    └── styles.scss               # imports Tailwind base styles, component styles and utility classes

└── ⚙️ 

```

## ⚙️ Setup

Make sure you have the latest version of [node.js](https://nodejs.org/en) installed (for instance via the [node version manager](https://github.com/nvm-sh/nvm) `nvm`).

Download and install [Angular CLI](https://v17.angular.io/cli) using the `npm` package manager (comes with node.js):

```bash

$ npm install -g @angular/cli

```

[**Windows**] Add node.js to your PATH environment variable:

- run `$ npm config get prefix` to retrieve the directory where npm will install global packages (e.g. `C:\Program Files\nodejs`)

- open "Edit the system environment variables" and navigate to "Environment Variables" -> "System Variables" -> "Path"

- edit "Path" and add the node.js directory path

- restart your PC and check if Angular CLI has been installed successfully by running `$ ng --version`

> [!NOTE]

> Be sure to run `$ npm ci` during the initial setup to install all required dependencies.

### Starting the app via Docker 🐋

Create an `.env` file in the root directory and paste the contents of the `.example.env` file.

> [!IMPORTANT]

> The application requires a SQLite database to function.

> This database is stored in an encrypted 7z archive at `src/server/data/ahb.db.encrypted.7z`.

> You will need the password to decrypt this archive, which can be found in the Hochfrequenz 1Password vault at [this link](https://start.1password.com/open/i?a=F35NURJ4PFGOPBA77PR66C5P4I&v=vjgfwz7dg5wg656rfpvadetrqy&i=grnjb4hn6ipcau4bqe43rkuwnq&h=hochfrequenz.1password.com).

>

> If you don't have access to the 1Password vault, please ask your teammates how to get the password.

>

> To work locally, you need to decrypt the archive and store the decrypted file in at `src/server/data/ahb.db`.

>

> If you want to start the application with Docker, you need to set the `DB_7Z_ARCHIVE_PASSWORD` environment variable in the `docker-compose.yaml` file either by setting it directly or by using the `.env` file.

> We recommend the latter to keep the `docker-compose.yaml` file clean and readable.

While having [Docker Desktop](https://www.docker.com/products/docker-desktop/) up and running, start the docker container using

```bash

$ docker compose up -d --build

```

and navigate to `http://localhost:4000/`.

If this fails to start because of azure-mock problems, just copy the _unencrypted_ database to `src/server/data/ahb.db` and start the Angular CLI server.

### Starting the app using Angular CLI

To start a dev server, run

```bash

$ ng serve

```

and navigate to `http://localhost:4200/`.

The application will automatically reload if you change any of the source files.

In order to start both the dev server as well as the server-side watch process to access the blob storage, run

```shell

$ npm run start

```

For further commands, refer to the scripts located in `package.json`.

## 🛠️ Build & Development

### Code scaffolding

Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.

### Build

Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory.

### Running unit tests

Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).

### Running end-to-end tests

Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To use this command, you need to first add a package that implements end-to-end testing capabilities.

### OpenAPI Specification Generation

Run `npm run ng-openapi-gen` to generate the OpenAPI specification and related TypeScript interfaces.

This command will update the API client code based on the OpenAPI specification.

## 🚀 Deployment

The application can be deployed to two environments: Stage and Production.

The deployment process is automated using a combination of GitHub Actions, Pulumi, and Octopus Deploy.

### Deployment Process Overview

1. **Build**: GitHub Actions builds a Docker image and pushes it to the GitHub Container Registry

2. **Infrastructure**: Pulumi manages the Azure resources

3. **Deployment**: Octopus Deploy handles the container deployment to Azure by using Pulumi.

### Stage Deployment

To deploy to the stage environment:

1. Set a new git tag in the format `v..-rc`, e.g. `v1.0.0-rc01`.

2. This will automatically trigger the deployment pipeline and creates a new GitHub pre-release.

3. The application will be deployed to [ahb-tabellen.stage.hochfrequenz.de](https://ahb-tabellen.stage.hochfrequenz.de).

### Production Deployment

To deploy to the production environment:

1. Set a new git tag in the format `v..`, e.g. `v1.0.0`.

2. This will trigger the deployment pipeline and creates a new GitHub release.

3. A manual approval step in [Octopus Deploy](https://hochfrequenz.octopus.app) will be required

4. After approval, the application will be deployed to [ahb-tabellen.hochfrequenz.de](https://ahb-tabellen.hochfrequenz.de)

## Update the database

### Overview

The `ahb.db` file is a SQLite database that contains AHB (Anwendungshandbuch) data for the energy industry.

This database serves as the primary data source for the AHB Tabellen application.

The database is created using the [fundamend](https://github.com/Hochfrequenz/xml-fundamend-python/) Python package, which processes XML files containing AHB specifications.

The [database generation script](https://github.com/Hochfrequenz/xml-migs-and-ahbs/blob/main/load_ahbs_into_sqlitedb.py) is located in a private repository that contains all the raw XML files from `bdew-mako.de`:

The source XML files must be paid for, so they are not publicly available, which is why the repository is private.

### Maintenance

To update the database with new AHB data:

1. Access the private [xml-migs-and-ahbs repository](https://github.com/Hochfrequenz/xml-migs-and-ahbs/)

2. If necessary, update the XML files by **manually** downloading them from the bdew-mako.de website because their API exists but is PITA. Commit the files to a feature branch and fix all the errors found by the CI before squashing to main.

3. [create a new release](https://github.com/Hochfrequenz/xml-migs-and-ahbs/releases/new) in the xml-migs-and-ahbs repository

4. after a few minutes, download the `ahb_.db.encrypted.7z ` from the release artifacts

5. copy the encrypted 7z file to [`/src/server/data/ahb.db.encrypted.7z`](/src/server/data/ahb.db.encrypted.7z) (and overwrite the previous file)

### Security

The database file is stored in an encrypted and compressed format (`ahb.db.encrypted.7z`) to protect sensitive data during storage and transmission.

The password for decryption can be found in the Hochfrequenz 1Password vault and the GitHub organization wide secrets.

For local testing it is sufficient to download the unencrypted `ahb_.db.7z` fron the release artifacts, un7zip it and place it next to the encrypted db as `ahb.db`.

## 🔗 Links

- Generate machine-readable files from AHB documents with [KohlrAHBi](https://github.com/Hochfrequenz/kohlrahbi) 🥬.

- Official edi@energy AHB documents are provided by BDEW at [edi-energy.de](https://www.edi-energy.de/index.php?id=38).

- To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.

## 📝 Changelog

The changelog is generated using [git-cliff](https://github.com/orhun/git-cliff) and is automatically added to the GitHub release.

To generate the changelog locally, run

```bash

$ git cliff -o CHANGELOG.md --github-token 

```

The github token is required to avoid rate limiting.