A2J / Access to Justice / Zugang zu Recht

This repository runs https://service.justiz.de/. We provide user-centered access to digital justice services. To find out more, check our project homepage

Requirements

• Node (>= 24)
• Docker (Redis, S3 bucket)

Local development

With Node installed, enable corepack (this only needs to happen once):

corepack enable

Then, install dependencies, start necessary services and run the app:

pnpm install
docker compose up -d
pnpm run dev

The app will be served on http://localhost:3000, assets are rebuilt on file save.

To explore the codebase, you can use this interactive code map.

Content

There are several options for fetching content: Local CMS, staging CMS, local content file. To find out more, check /doc/content.md.

Tests

Unit tests

• run: pnpm run test
• run in watch mode: pnpm run test:watch
• run with coverage: pnpm run test:coverage
• run subset: pnpm run test "STRING_TO_MATCH"

Test cases are defined as follows:

weitereAngaben: [                               <--- Descriptive test name containing an array of steps
    {                                           |
        stepId: "/persoenliche-daten/beruf",    |
        userInput: {                            | Discrete step in a flow, usually containing both the
            beruf: "Softwareentwickler:in",     | stepId, and any user-entered data (will be validated
        },                                      | against pageSchema)
    }                                           |
    {
        stepId: "/weitere-angaben",
        userInput: {
            weitereAngaben: "",
        },
    }
]

Testing arrays

Below you'll find an example of how to test adding array items:

{
    stepId: "/finanzielle-angaben/eigentum-zusammenfassung/zusammenfassung",   <--- Start from summary page
    addArrayItemEvent: "add-geldanlagen",                                      <--- Explicitly name the add array item event
                                                                                    to trigger special array item logic
},
{
    stepId: "/finanzielle-angaben/eigentum-zusammenfassung/geldanlagen/0/art", <--- Explicitly add array index, 0 here
    userInput: {
        "geldanlagen#art": "wertpapiere",                                      <--- Hashtax syntax matches pageSchemas
        geldanlagen: [                                                         |
            {                                                                  | Many steps include guards that explicitly check
            art: "wertpapiere",                                                | array indices and array items' properties. For this,
            },                                                                 | you need to define the array itself, as well as
        ],                                                                     | the pageData containing arrayIndexes, in order
        pageData: { arrayIndexes: [0] },                                       | for the test to pass
    },
},
{
    stepId:
    "/finanzielle-angaben/eigentum-zusammenfassung/geldanlagen/0/wertpapiere",
    userInput: {
        "geldanlagen#eigentuemer": "myself",
        "geldanlagen#wert": "1000",
    },
},
...

Skipping pageSchema validation

Often you'll find yourself testing a transition between states in which previously-entered user data is relevant for the purposes of a guard, but irrelevant for validating against the current page's pageSchema. Here we'll want to use the skipPageSchemaValidation property:

partnerschaftYes: [
    {
      stepId: "/finanzielle-angaben/eigentum/eigentum-info",                    <--- Step without pageSchema
      skipPageSchemaValidation: true,
      userInput: { partnerschaft: "yes" },                                      <--- User data, entered sometime before this step
    },
    {
      stepId: "/finanzielle-angaben/eigentum/heirat-info",                      <--- Guarded step, requiring partnerschaft: "yes"
    },
]

E2E tests

• run: pnpm run test:e2e
• UI: pnpm run test:e2e:ui

For more details, check /doc/e2e-tests.md

Git Hooks

We use lefthook for running several pre-push hooks when pushing on main, install them using pnpm run init.

The git hooks check formatting, linting, unit tests, typecheck. You may execute them before committing using lefthook run pre-push. See lefthook.yaml for more details.

Storybook

Storybook containing our components is running on staging and preview. To run it locally, use pnpm run start:storybook.

Known issues

When running S3 LocalStack alongside an AVM FritzBox, you might encounter issues accessing LocalStack due to DNS rebind protection. For more details, you can check this guide and this discussion.

To resolve this, you need to allow localhost.localstack.cloud in your FritzBox's DNS Rebind Protection settings. You can find step-by-step instructions here, and be sure to select your router model.

Code Language Conventions

This project uses a hybrid approach to language in code, mixing English and German. While technical implementation uses English (e.g., function validateData()), domain-specific terms can be kept in German (e.g., hasRechtsschutzversicherung: boolean). This is crucial because many German administrative terms lack precise English equivalents, leading to inconsistencies and communication overhead when translated. This hybrid approach ensures clear communication with domain experts and maintains code readability within our specific context. While we acknowledge this might pose a barrier for non-German speaking contributors, we believe it's the most effective solution for our project. We encourage contributors to ask questions about any unfamiliar German terms.

Contributing

Deutsche Sprache weiter unten

Everyone is welcome to contribute! You can contribute by giving feedback, adding issues, answering questions, providing documentation or opening pull requests. Please always follow the guidelines and our Code of Conduct.

To contribute code, simply open a pull request with your changes and it will be reviewed by someone from the team. By submitting a pull request you declare that you have the right to license your contribution to the DigitalService and the community under the MIT License.

Mitwirken

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

Um Code beizutragen, erstelle einfach einen Pull-Request mit deinen Änderungen, dieser wird dann von einer Person aus dem Team überprüft. Durch das Eröffnen eines Pull-Request erklärst du ausdrücklich, dass du das Recht hast, deine Beitrag an den DigitalService und die Community unter der MIT License zu lizenzieren.