RIS Norms

All modules	Frontend	Backend

This repository contains a web app supporting the Federal Documentation of Statutes (DE: "Normendokumentation"). It is part of NeuRIS. You can learn more about NeuRIS on our website.

Quickstart

If you're already familiar with our stack and the project, here is a list of the most important commands for running frequent tasks. You will find more detailed instructions below.

Test user credentials

When running the application locally, use the following test user credentials:

• Username: jane.doe
• Password: test

Running backend + frontend separately

# Run Docker containers (working dir: project root)
docker compose -f docker-compose-services.yaml up -d

# Run backend (working dir: `./backend`)
./gradlew bootRun

# Install frontend dependencies and run frontend (working dir: `./frontend`)
npm install
node --run dev

You can open the frontend at http://localhost:5173.

Running a full, containerized build locally

# (working dir: project root)
docker compose up -d

You can open the frontend at http://localhost:8080.

Testing

Backend:

./gradlew test            # Unit tests
./gradlew integrationTest # Integration tests
./gradlew build           # Build with all checks, including tests and code style

Frontend:

node --run test       # Unit tests (once)
node --run test:watch # Unit tests (watch mode)
node --run test:a11y  # Accessibility tests

E2E tests (included in the frontend module, backend and frontend must be running separately):

node --run test:browsers                                    # E2E tests in Chrome and Firefox
node --run test:e2e -- --project <chromium|firefox>  # E2E tests for a specific browser
node --run test:e2e -- --ui                                 # Opens the Playwright UI for testing

Code style & quality

Backend:

./gradlew spotlessApply   # Format code

Frontend:

node --run style:fix    # Check code conventions + formatting, attempt to fix
node --run typecheck    # Check TypeScript validity

Building

Backend:

./gradlew build

Frontend:

node --run build

# Optionally, preview the build output (requires a running backend):
node --run preview

Navigating the repository

This is a mono-repository containing:

Module	Notes
.github	GitHub configuration, including automated pipelines
backend	The backend service (Java + Spring Boot)
doc	Additional documentation, including Architecture Decision Records (ADRs) and API specifications
frontend	A browser-based interface for users (TypeScript + Vue + Tailwind)
LegalDocML.de	Schemas, examples, test data, and custom extensions to LegalDocDML.de
local	Additional setup for local development
regex	Utilities for creating regex schemas

Prerequisites

To build and run the application, you'll need:

• Docker, for infrastructure or running a containerized version of the entire application locally
• A Java 21-compatible JDK
• A recent version of Node (you'll find the exact version we're using here)

If you would like to make changes to the application, you'll also need:

• jq, for parsing license data
• talisman, for preventing accidentially committing sensitive data
• lefthook, for running Git hooks
• gh, for checking the pipeline status before pushing
• (optional) adr-tools, for scaffolding new ADRs
• (optional) nvm, for managing Node versions

If you use Homebrew, you can install all of them like this:

brew install openjdk@21 jq talisman lefthook gh adr-tools nvm
brew install --cask docker # or `brew install docker` if you don't want the desktop app

Once you installed the prerequisites, make sure to initialize Git hooks. This will ensure any code you commit follows our coding standards, is properly formatted, and has a commit message adhering to our conventions:

lefthook install

Finally, there are some environment variables that need to be set locally. As a starting point, copy the frontend/.env.local.example file, and rename it to .env.local. Learn more about environment variables here.

Learn more

You will find more information about each module in the respective folders. If you're getting started, the READMEs of the backend and frontend will be the most relevant resources.

License checking

When installing dependencies, make sure they are licensed under one of the allowed licenses. This will be checked in the pipeline for both frontend and backend dependencies. The pipeline will fail if licenses not included in the list are used by any dependency.

Contributing

If you would like to contribute, check out CONTRIBUTING.md. Please also consider our Code of Conduct.

Additional resources

• 🔒 RIS Reports (additional documentation, including architecture diagrams and JavaDocs)
• 🔒 Infrastructure
• 🔒 Importer for migrated data