A2J - Kommunikationsplattform

Prerequisites

Node.js and Homebrew

We aim to use the current active LTS version of Node.js, which is V24 at the time of writing. There is a .nvmrc file to simplify setup using nvm (install Node version by running nvm current) and a .tool-versions file to install Node.js with asdf (check and install used Node version by running asdf current and/or asdf install nodejs XX.XX.X).

Additionally we use Git Hooks that can be installed with Homebrew, please check if brew is available on your machine with brew -v command.

Dependencies

Disable execution of npm scripts to reduce attack surface for supply chain attacks:

npm config set ignore-scripts true

Then, install npm dependencies:

npm install

Playwright

For E2E and a11y testing with Playwright you will need to install the supported browsers:

npx playwright install

Git Hooks

For the provided Git hooks you will need to install lefthook (git hook manager) and talisman (secrets scanner) brew install lefthook talisman. Afterwards execute lefthook install to initialize the hooks or run lefthook run pre-commit before commiting new changes. See lefthook.yml for more details in regards to the currently configured git hooks.

Everything else

• Please have a look at conventional commit messages to know how to write Git Commit Messages.

Development

Configure .env variables

Copy the .env.example file and save it as .env within this projects root folder and define the needed environment variables. For example:

ENVIRONMENT=development

Local development

From your terminal:

npm run dev

This starts your app in development mode, rebuilding assets on file changes.

XJustiz test files

An XJustiz file is required to submit a new claim (this is called “Klageeinreichung” in German). Test files are stored in the /data/xjustiz/** folder. Further information regarding the XJustiz-standard can be found here.

OpenAPI Specification of Justiz-Backend-API

The OpenAPI Specification of the Justiz-Backend-API (Single Source of Truth for the external backend service) is stored within the /data/api/ folder (file: /data/api/openapi.json).

# Read from OpenAPI file and output generated code for custom mocking with MSW (see: /mocks/api/*.js)
npx msw-auto-mock data/api/openapi.json -o ./msw-auto-mock

The data of /mocks/api/** was initialized with the help of msw-auto-mock and then individually adapted to all our user journeys. Therefore, we should bear in mind that OpenAPI Spec updates (data/api/openapi.json) may lead to manual customizations within the mocks/api/** handlers.

Testing

The application has

• unit tests (using Vitest)
  • Stateless/static Components can be excluded from code coverage (SonarQube and Vitest) by using the following file naming convention: ComponentName.static.tsx
• end-to-end tests (using Playwright)
• accessibility tests (using Playwright and Axe)

Test commands

• Run unit tests: npm test
• Run unit tests in watch mode: npm run test:watch
• Run E2E tests: npm run test:e2e
• Run A11y tests: npm run test:a11y
• Generate test coverage: npm run test:generate-coverage (used by SonarQube)

Code quality checks (linting & formatting)

The project uses ESLint for linting and Prettier. for formatting.

Commands

• Check formatting: npm run format:check
• Autofix formatting issues: npm run format:fix
• Check lint: npm run lint:check
• Autofix lint issues: npm run lint:fix
• Check style (formatting & linting): npm run style:check
• Autofix style issues (formatting & linting): npm run style:fix

Deployment

Build and run the app in production mode:

npm run build
npm start

Docker

The project includes a Dockerfile to create a Docker Image for the project.

You can build the Docker Image using

docker build -t a2j-kommunikationsplattform .

and then start it using

docker run -d -p 3000:3000 --name a2j-kommunikationsplattform a2j-kommunikationsplattform

The website is then available under http://localhost:3000

If you want to include any additional files during the build that are not in the app directories you need to add them to the .dockerignore file.

The .github/workflows/pipeline.yml GitHub Action includes a build-and-push-image job to build the Docker Image and push it to GitHub Packages.

Architecture Decision Records

The docs/adr directory contains architecture decisions. For adding new records the adr-tools command-line tool is useful but not strictly necessary:

brew install adr-tools

Contributing

🇬🇧 Everyone is welcome to contribute the development of the a2j-kommunikationsplattform. You can contribute by opening pull request, providing documentation or answering questions or giving feedback. Please always follow the guidelines and our Code of Conduct.

🇩🇪 Jede:r ist herzlich eingeladen, die Entwicklung der a2j-kommunikationsplattform mitzugestalten. Du kannst einen Beitrag leisten, indem du Pull-Requests eröffnest, die Dokumentation erweiterst, Fragen beantwortest oder Feedback gibst. Bitte befolge immer die Richtlinien und unseren Verhaltenskodex.

Contributing code

🇬🇧 Open a pull request with your changes and it will be reviewed by someone from the team. When you submit a pull request, you declare that you have the right to license your contribution to the DigitalService and the community. By submitting the patch, you agree that your contributions are licensed under the MIT license.

Please make sure that your changes have been tested befor submitting a pull request.

🇩🇪 Nach dem Erstellen eines Pull Requests wird dieser von einer Person aus dem Team überprüft. Wenn du einen Pull-Request einreichst, erklärst du dich damit einverstanden, deinen Beitrag an den DigitalService und die Community zu lizenzieren. Durch das Einreichen des Patches erklärst du dich damit einverstanden, dass deine Beiträge unter der MIT-Lizenz lizenziert sind.

Bitte stelle sicher, dass deine Änderungen getestet wurden, bevor du einen Pull-Request sendest.