EmpiRE-Compass
"A Neuro-Symbolic Dashboard for Navigating the Knowledge Landscape of Empirical Research Practice in Requirements Engineering"

Important

Visit the live version of EmpiRE-Compass.

Table of Contents

Contents

1. About the Project
2. Key Features
3. Folder Structure and Files
4. Installation Instructions
5. Design System & Storybook
6. API Documentation (Swagger)
7. Firebase Setup
8. Statistics Automation
9. Repository Links
10. Related Publications
11. Corresponding Author
12. How to Cite

About the Project

EmpiRE-Compass is a neuro-symbolic dashboard that facilitates the exploration, synthesis, and reuse of knowledge about empirical research practice in Requirements Engineering (RE). It integrates two complementary layers: A symbolic layer based on the Open Research Knowledge Graph (ORKG) for structured, machine-actionable knowledge, and a neural layer leveraging large language models (LLMs) to answer both predefined and custom competency questions. This dual approach enables researchers to navigate the evolving knowledge landscape of empirical research practice in RE, identify reusable insights across publications, and promote Open Science through transparent, interoperable knowledge representations. EmpiRE-Compass currently focuses on two themes: Empirical research practices in RE using KG-EmpiRE, and empirical research practices in Natural Language Processing for RE using the NLP4RE ID Card.

EmpiRE-Compass.mov

(back to top)

Key Features

EmpiRE-Compass offers a rich set of capabilities to support exploration, synthesis, and reuse of knowledge about empirical research practice in RE. Its exploratory visual analytics provide detailed insights into the state and evolution of the field through interactive charts and distributions. The platform’s neuro-symbolic synthesis combines structured knowledge graphs with neural large language models to answer competency questions, interpret findings, and support contextual knowledge integration. All structured data, SPARQL queries, analyses, and interpretations are openly available to foster replicable research and long-term reuse. EmpiRE-Compass is built on FAIR principles — ensuring that knowledge is findable, accessible, interoperable, and reusable — and is grounded in Open Science values of transparency, ethical attribution, and collaborative maintenance. Developed on top of the ORKG and supported by TIB, the platform is designed for community-driven contributions and long-term sustainability.

(back to top)

Folder Structure and Files

In the following, we first show a graphical overview of the folder structure and files of the project before we describe them in more detail.

(back to top)

Description of the Folders and Files

Directory / File	Description
.storybook/	Storybook configuration files.
backend/	Node.js backend server for API handling.
scripts/	Python scripts for data processing and statistics.
src/api/	SPARQL query constants and definitions.
src/auth/	Keycloak authentication logic and contexts.
src/components/	Reusable React components.
src/components/Admin/	Components for the administration dashboard.
src/components/AI/	AI Assistant, Chat interface, and Logic.
src/components/CustomCharts/	Custom visualization components using Recharts/MUI.
src/firestore/	Services for interacting with Firebase Firestore.
src/hooks/	Custom React hooks (e.g., useAIAssistant, useAuth).
src/pages/	Top-level page components corresponding to routes.
src/services/	API services for Backend and AI integration.
src/store/	Redux store slices (aiSlice, questionSlice).
src/templates/	JSON schemas defining research domain templates.
src/utils/	Utility functions for data formatting and processing.
package.json	Project dependencies and npm scripts.
vite.config.ts	Configuration for the Vite build tool.

(back to top)

Installation Instructions

In the following, we explain how to install and run the project locally using a terminal, assuming that the prerequisites are met.

1. Ensure prerequisites are installed

• Node.js (version 18 or higher recommended)
• Modern web browser (e.g., Chrome, Firefox)
• Git (optional, for version control)

2. Clone the repository

git clone https://github.com/okarras/EmpiRE-Compass.git

3. Navigate to the main project directory

cd EmpiRE-Compass

4. Install dependencies

Using npm:

npm install

5. Configure environment variables

Frontend Configuration

Copy the example environment file and configure your variables:

cp .env.example .env

Edit the .env file with your actual values. The .env.example file contains all necessary environment variables including:

• Backend API URL: VITE_BACKEND_URL
• Keycloak Authentication (optional): VITE_KEYCLOAK_URL, VITE_KEYCLOAK_REALM, VITE_KEYCLOAK_CLIENT_ID
• Firebase Configuration: VITE_FIREBASE_API_KEY, VITE_FIREBASE_AUTH_DOMAIN, VITE_FIREBASE_PROJECT_ID, etc.
• AI Provider API Keys (optional): VITE_OPEN_AI_API_KEY, VITE_GROQ_API_KEY, VITE_MISTRAL_API_KEY, VITE_GOOGLE_GENERATIVE_AI_API_KEY

Note:

• The application will work without Keycloak configuration, but authentication features (login/logout) and admin routes will not be available.
• AI API keys can also be configured directly in the UI. If you set them in .env, enable "Use Environment Keys" in the AI configuration settings.
• The dashboard and public features will function normally in unauthenticated mode.

Backend Configuration (if running backend locally)

If you're running the backend server locally, configure backend environment variables:

cd backend
cp .env.example .env

Edit backend/.env with your backend configuration including:

• Server Port: PORT
• AI Provider: AI_PROVIDER (openai, groq, mistral, or google)
• AI Models: OPENAI_MODEL, GROQ_MODEL, MISTRAL_MODEL, GOOGLE_MODEL
• AI API Keys: OPENAI_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY

6. Start the development server

Using npm:

npm run dev

7. Open the application in your browser

Visit:

http://localhost:5173

(back to top)

Design System & Storybook

EmpiRE-Compass includes a comprehensive design system documented in Storybook, providing a complete library of reusable UI components.

📚 Storybook (Component Library)

Live Documentation: https://empire-compass-storybook.tib.eu

Component Categories

• 🏠 Home Components: Hero sections, feature highlights, contact forms
• 📊 Data Visualization: Custom charts, statistics cards, interactive graphs
• 🤖 AI Components: AI assistant interface, chat messages, dynamic questions
• 🛡️ Admin Components: Dashboard tools, settings, data management
• 🔧 Layout Components: Headers, navigation, responsive containers
• ⚙️ Utility Components: Loading states, error handling, form elements

Technology Stack

• React 18 with TypeScript
• Material-UI (MUI) component library
• Storybook 7+ for documentation
• Chromatic for visual testing (planned)

Local Development

# Start Storybook locally
npm run storybook

# Build Storybook for deployment
npm run build-storybook

# Preview built Storybook
npm run preview:storybook

(back to top)

API Documentation (Swagger)

EmpiRE-Compass provides a comprehensive REST API documented with Swagger/OpenAPI, enabling programmatic access to AI services and backend functionality.

📚 API Documentation

Live Documentation: https://empire-compass-backend.tib.eu/api-docs/

Available Endpoints

• 🤖 AI Services: /api/ai/* - AI-powered question answering and chat
• ❤️ Health Check: /api/health - Service health and status monitoring
• 📊 Templates: /api/templates/* - Research domain templates
• 👥 Users: /api/users/* - User management
• 📝 Request Logs: /api/request-logs/* - API usage tracking
• 🏠 Home Content: /api/home-content/* - Dynamic content management

Technology Stack

• Express.js backend with TypeScript
• Swagger UI for interactive API documentation
• OpenAPI 3.1 specification
• AI SDK integration (OpenAI, Groq, Mistral, Google)

Local Development

# Navigate to backend directory
cd backend

# Install dependencies
npm install

# Start backend server
npm run dev

# Access local API docs
# http://localhost:5001/api-docs

(back to top)

Firebase Setup

EmpiRE-Compass uses Firebase Firestore for real-time data storage, statistics, and content management. Follow these guides to set up Firebase integration:

📚 Firestore Tutorial

For a comprehensive guide on Firestore, refer to the official documentation:

• Firestore Documentation & Tutorial - Learn Firestore basics, data modeling, and best practices

Quick Setup (5 minutes)

📋 Firebase Quick Setup Guide - Fast-track setup with essential steps

Detailed Setup

📖 Complete Firebase Setup Guide - Comprehensive guide with troubleshooting

Connecting Firebase to Your Project

1. Create a Firebase Project

1. Go to Firebase Console
2. Click Add project or select an existing project
3. Follow the setup wizard to create your project

2. Enable Firestore Database

1. In Firebase Console, navigate to Firestore Database
2. Click Create database
3. Choose Start in test mode (you can configure security rules later)
4. Select a location for your database

3. Get Firebase Configuration

1. Go to Project Settings (gear icon) → General tab
2. Scroll down to Your apps section
3. Click the Web icon (</>) to add a web app
4. Register your app and copy the Firebase configuration object
5. Add these values to your .env file (see .env.example for reference):
   • VITE_FIREBASE_API_KEY
   • VITE_FIREBASE_AUTH_DOMAIN
   • VITE_FIREBASE_PROJECT_ID
   • VITE_FIREBASE_STORAGE_BUCKET
   • VITE_FIREBASE_MESSAGING_SENDER_ID
   • VITE_FIREBASE_APP_ID
   • VITE_FIREBASE_MEASUREMENT_ID (optional, for Analytics)

4. Create Required Firestore Collections

EmpiRE-Compass requires the following Firestore collections. You can create them manually or they will be created automatically when the app runs:

Templates Collection (Main collection)

Templates (collection)
  └─ {templateId} (document)
      ├─ id: string
      ├─ title: string
      ├─ collectionName: string
      ├─ description?: string
      ├─ Questions (subcollection)
      │   └─ {questionId} (document)
      │       ├─ id: number
      │       ├─ uid: string
      │       ├─ title: string
      │       ├─ dataAnalysisInformation: object
      │       └─ sparqlQuery: string
      └─ Statistics (subcollection)
          └─ {statisticId} (document)
              ├─ id: string
              ├─ name: string
              ├─ paperCount: number
              ├─ total_resources: number
              ├─ total_literals: number
              ├─ total_predicates: number
              ├─ total_statements: number
              ├─ venueCount: number
              ├─ global_distinct_resources: number
              ├─ global_distinct_literals: number
              ├─ global_distinct_predicates: number
              └─ updatedAt: timestamp

To create manually:

1. In Firestore Console, click Start collection
2. Collection ID: Templates
3. Create a document with ID matching your template (e.g., R186491 for KG-EmpiRE)
4. Add fields: id (string), title (string), collectionName (string)

HomeContent Collection

HomeContent (collection)
  └─ sections (document)
      ├─ header: { title: string, subtitle: string }
      ├─ aboutProject: { title: string, content: string, themes: string[] }
      ├─ keyFeatures: { title: string, features: Array<{title: string, description: string}> }
      ├─ futureDevelopment: { title: string, intro: string, phases: Array<{phase: string, goal: string}> }
      ├─ contact: { title: string, name: string, position: string, organization: string, address: string[], email: string }
      ├─ partners: { title: string, partners: Array<{label: string, link: string, logoUrl: string}> }
      └─ templates: Array<{ id: string, title: string, description: string }>

To create manually:

1. Create collection: HomeContent
2. Create document with ID: sections
3. Add the structure above (can be initialized with default values)

Users Collection (Optional - for authentication)

Users (collection)
  └─ {userId} (document)
      ├─ id: string
      ├─ email: string
      ├─ display_name: string
      └─ ... (other user fields)

Note: This collection is created automatically when users authenticate via Keycloak.

5. Configure Security Rules

For production, update your Firestore security rules. Example rules:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Templates collection - read public, write requires auth
    match /Templates/{templateId} {
      allow read: if true;
      allow write: if request.auth != null;

      match /Questions/{questionId} {
        allow read: if true;
        allow write: if request.auth != null;
      }

      match /Statistics/{statisticId} {
        allow read: if true;
        allow write: if request.auth != null;
      }
    }

    // HomeContent - read public, write requires auth
    match /HomeContent/{document=**} {
      allow read: if true;
      allow write: if request.auth != null;
    }

    // Users - read own data, write own data
    match /Users/{userId} {
      allow read: if request.auth != null && request.auth.uid == userId;
      allow write: if request.auth != null && request.auth.uid == userId;
    }
  }
}

6. Generate Service Account (for Backend/Statistics)

1. Go to Project Settings → Service Accounts
2. Click Generate New Private Key
3. Download the JSON file securely
4. For GitHub Actions: Add the entire JSON content as FIREBASE_SERVICE_ACCOUNT_KEY secret
5. For local development: Place the JSON file in scripts/ directory (ensure it's in .gitignore)

Firebase Configuration Steps:

1. Create Firebase Project - Set up a new project in Firebase Console
2. Enable Firestore - Create Firestore database in test mode
3. Get Configuration - Copy Firebase config to .env file
4. Create Collections - Set up Templates and HomeContent collections (or let the app create them)
5. Generate Service Account - Download the service account JSON key for backend operations
6. Configure GitHub Secret - Add FIREBASE_SERVICE_ACCOUNT_KEY to repository secrets (if using GitHub Actions)
7. Test Integration - Run the app to verify Firebase connection

Local Development

# Validate your Firebase JSON file
cd scripts
python validate_firebase_json.py path/to/your/service-account.json

# Test Firebase integration
python firebase_integration.py

# Run statistics update locally
python empire-statistics.py --service_account path/to/service-account.json --limit 5

(back to top)

Statistics Automation

EmpiRE-Compass automatically updates statistics using GitHub Actions that run the empire-statistics.py script:

Automated Updates

• On every commit to main branch
• On merged pull requests
• Weekly schedule (Mondays at 6 AM UTC)
• Manual trigger via GitHub Actions

Statistics Collected

• Paper count - Total number of papers in KG-EmpiRE
• Resources & Literals - RDF resources and literal values
• Predicates - RDF predicates and properties
• Distinct counts - Unique resources, literals, and predicates
• Averages - Mean values per paper
• Timestamps - Last update and processing times

Manual Execution

# Process all papers and update Firebase
python scripts/empire-statistics.py --service_account path/to/service-account.json

# Test with limited papers
python scripts/empire-statistics.py --limit 10 --service_account path/to/service-account.json

# Skip Firebase update (CSV only)
python scripts/empire-statistics.py --no_firebase

Monitoring

• View execution logs in GitHub Actions tab
• Check results in Firebase Console → Firestore Database
• Download CSV reports from workflow artifacts

(back to top)

Repository Links

EmpiRE-Compass: https://github.com/okarras/EmpiRE-Compass
EmpiRE-Analysis: https://github.com/okarras/EmpiRE-Analysis
Storybook (Design System): https://empire-compass-storybook.tib.eu/?path=/docs/layout-menudrawer--docs
API Documentation (Swagger): https://empire-compass-backend.tib.eu/api-docs/

(back to top)

Related Publications

The first version of KG-EmpiRE based on 570 papers from the IEEE International Conference on Requirement Engineering from 2000 to 2022 and the first analysis of the sustainable literature review on the state and evolution of empirical research in RE have been published in:

Oliver Karras, Felix Wernlein, Jil Klünder, and Sören Auer:
Divide and Conquer the EmpiRE: A Community-Maintainable Knowledge Graph of Empirical Research in Requirements Engineering, In: 2023 ACM/IEEE International Symposium on Empirical Software Engineering and Measurement (ESEM), New Orleans, LA, USA, 2023, pp. 1-12.

The publication received the of the 17th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement 2023.

The second version KG-EmpiRE based on 680 papers from the IEEE International Conference on Requirement Engineering from 1994 to 2022 and the analysis of the sustainable literature review on the state and evolution of empirical research in RE have been published in:

Oliver Karras:
KG-EmpiRE: A Community-Maintainable Knowledge Graph for a Sustainable Literature Review on the State and Evolution of Empirical Research in Requirements Engineering, In: 2024 IEEE International Requirements Engineering Conference (RE), Reykjavík, Iceland, 2024.

The artifact received the , the , and from the Artifact Evaluation track of the 32nd IEEE International Requirements Engineering Conference 2024.

(back to top)

Corresponding Author

Dr. rer. nat. Oliver Karras

Researcher and Data Scientist - Open Research Knowledge Graph

TIB - Leibniz Information Centre for Science and Technology

Welfengarten 1B

30167 Hannover

E-Mail: oliver.karras@tib.eu

(back to top)

How to Cite

If you want to cite this project, we suggest using the following reference:

Oliver Karras, Amirreza Alasti, Sushant Aggarwal, Yücel Celik, and Lena John:
EmpiRE-Compass, Computer Software, Version v1.4, https://github.com/okarras/EmpiRE-Compass, 2025.

You can also use the "Cite this repository" function in the top right menu, resulting from the included citation file format file for human- and machine-readable citation information for software and datasets. Further information can be found on the Citation File Format (CFF) website.

If you want to cite the related publications, use the references in the section related publications.

(back to top)

Released under MIT by Oliver Karras.