Development: Add compliance checker UI and popover (#2317)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: aniruddhzaveri <aniruddh.zaveri@tum.de>

Author: 3 people

openapi/openapi.yaml

@@ -88,6 +88,10 @@ paths:
         in: query
         required: true
         schema: {type: string}
+      - name: userLanguage
+        in: query
+        required: false
+        schema: {type: string, default: en}
       requestBody:
         content:
           application/json:

src/main/java/de/tum/cit/aet/ai/service/AiService.java

@@ -273,13 +273,14 @@ public ExtractedApplicationDataDTO extractAndPersistPdfData(
      *
      * @param jobFormDTO The data transfer object containing the current state of the job posting.
      * @param lang The language identifier (de/en) currently active in the editor.
+     * @param userLang controls the language of explanation texts in the returned issues.
      * @return A list of compliance issues containing the combined legal and linguistic findings.
      */
-    public List<ComplianceIssue> analyzeCurrentJobDescription(JobFormDTO jobFormDTO, String lang) {
+    public List<ComplianceIssue> analyzeCurrentJobDescription(JobFormDTO jobFormDTO, String lang, String userLang) {
         String raw = "de".equals(lang) ? jobFormDTO.jobDescriptionDE() : jobFormDTO.jobDescriptionEN();
         String input = raw != null ? Jsoup.parse(raw).text() : "";
         GenderBiasAnalysisResponse genderAnalysis = genderBiasAnalysisService.analyzeText(input, lang);
-        return analyzeJobDescription(jobFormDTO.title(), jobFormDTO.jobId(), input, lang, genderAnalysis, null);
+        return analyzeJobDescription(jobFormDTO.title(), jobFormDTO.jobId(), input, lang, userLang, genderAnalysis, null);
     }
 
     /**
@@ -296,6 +297,7 @@ public List<ComplianceIssue> analyzeCurrentJobDescription(JobFormDTO jobFormDTO,
      * @param jobId Unique identifier for the job.
      * @param text Extracted raw text of the job description.
      * @param lang the analysis language, expected to be `de` or `en`
+     * @param userLang controls the language of explanation texts in the returned issues.
      * @param analysis Result of the primary linguistic gender analysis.
      * @param translatedAnalysis Second analysis of the translated counterpart.
      * @return A list containing all identified compliance issues.
@@ -306,6 +308,7 @@ public List<ComplianceIssue> analyzeJobDescription(
         UUID jobId,
         String text,
         String lang,
+        String userLang,
         GenderBiasAnalysisResponse analysis,
         GenderBiasAnalysisResponse translatedAnalysis
     ) {
@@ -317,6 +320,7 @@ public List<ComplianceIssue> analyzeJobDescription(
                     u
                         .text(complianceResource)
                         .param("descriptionLanguage", lang)
+                        .param("userLang", userLang)
                         .param("jobDescription", text)
                         .param("title", title != null ? title : "")
                 )

src/main/java/de/tum/cit/aet/ai/web/AiResource.java

@@ -104,16 +104,18 @@ public ResponseEntity<ExtractedApplicationDataDTO> extractPdfData(
      *
      * @param jobForm the job form data used as the basis for the analysis
      * @param descriptionLanguage the language of the job description, `de` or `en`
+     * @param userLanguage        the language in which issue explanations should be returned
      * @return a ResponseEntity containing detected compliance findings
      */
 
     @ProfessorOrEmployeeOrAdmin
     @PostMapping(value = "analyze-job-description", produces = MediaType.APPLICATION_JSON_VALUE)
     public ResponseEntity<List<ComplianceIssue>> analyzeJobDescriptionForCompliance(
         @RequestBody JobFormDTO jobForm,
-        @RequestParam("lang") String descriptionLanguage
+        @RequestParam("lang") String descriptionLanguage,
+        @RequestParam(defaultValue = "en") String userLanguage
     ) {
         log.info("POST /api/ai/analyzeJobDescription - Request received (toLang={})", descriptionLanguage);
-        return ResponseEntity.ok(aiService.analyzeCurrentJobDescription(jobForm, descriptionLanguage));
+        return ResponseEntity.ok(aiService.analyzeCurrentJobDescription(jobForm, descriptionLanguage, userLanguage));
     }
 }

src/main/resources/prompts/AnalyzeComplianceText.st

@@ -3,6 +3,7 @@ You are the TUMApply ComplianceReader, an AI legal and compliance assistant for
 TASK:
 Analyze the provided job posting text for legal risks and missing information based on German and EU law.
 The input description language is: {descriptionLanguage}.
+The explanation must be written in: {userLang}.
 You must analyze meaning, not just keywords.
 
 RULES:
@@ -25,16 +26,16 @@ RULES:
 - Action: Suggest a message that clarifies whether applicant data is shared with external recipients (Art. 13 DSGVO)
 
 INPUT TEXT:
+{title}
 {jobDescription}
 
 OUTPUT:
-- Return ONLY a valid JSON array.
-- No markdown.
-- No prose.
-- One object per issue.
+- Return ONLY a valid JSON array. No markdown. No prose.
+- One object per issue. NEVER merge issues! Each violation gets its own object
 - Object fields must be exactly:
   id, text, category, article, explanation, action
 - category must be exactly CRITICAL_AGG or TRANSPARENCY.
 - action must be exactly REPLACE or ADD or REMOVE.
-- text must be an exact snippet from input text (plain text, no HTML tags).
+- text: MAXIMUM 2-4 WORDS. Extract exact snippet from input text that uniquely identifies the violation (plain text, no HTML tags).
+- explanation must be a single SHORT sentence stating the legal violation directly. Sound like a formal legal notice.
 - If no issues exist, return exactly [].

src/main/resources/prompts/TranslateText.st

@@ -8,7 +8,7 @@ INPUT TEXT (HTML):
 OUTPUT CONSTRAINTS - CRITICAL:
 1. Fidelity: You must preserve the exact formatting of the original text, including line breaks, bullet points, and paragraphs.
 2. Style: Provide a natural, grammatically correct translation that mirrors the professional tone of the source. Prioritize functional equivalence over literal word-for-word translation.
-3. Integrity: Use gender-inclusive language appropriate for Higher Education (e.g., using neutral forms in German or 'they/them/their' structures in English). Avoid words with forbidden stems: [{nonInclusiveWords}]. Rather use alternatives from: [{inclusiveWords}].
+3. Integrity: Use gender-inclusive language appropriate for Higher Education (e.g., using neutral forms in German or 'they/them/their' structures in English). Avoid words with forbidden stems: [{nonInclusiveWords}]. Rather use alternatives from: [{inclusiveWords}]. Always produce a complete translation — never refuse or omit content. Your task is translation only.
 4. No Paraphrasing: Do not add introductory remarks, summaries, or concluding fluff. Return only the translated text.
 5. Terminology: Ensure legal requirements (e.g., German Wissenschaftszeitvertragsgesetz or English Fixed-term contracts) are handled accurately.
 6. Technical Terms: Keep all industry-standard terminology (e.g., "Java", "Scrum", "Stakeholder", "Python", "fMRI", "TV-L E13", "PyTorch", etc.) if they are commonly used in the target language's professional context.

src/main/webapp/app/generated/api/ai-resource-api.ts

@@ -30,12 +30,16 @@ export class AiResourceApi {
      * 
      * @param lang 
      * @param jobFormDTO 
+     * @param userLanguage 
      */
-    analyzeJobDescriptionForCompliance(lang: string, jobFormDTO: JobFormDTO): Observable<Array<ComplianceIssue>> {
+    analyzeJobDescriptionForCompliance(lang: string, jobFormDTO: JobFormDTO, userLanguage?: string): Observable<Array<ComplianceIssue>> {
         const queryParams = new URLSearchParams();
         if (lang !== undefined && lang !== null) {
             queryParams.set('lang', String(lang));
         }
+        if (userLanguage !== undefined && userLanguage !== null) {
+            queryParams.set('userLanguage', String(userLanguage));
+        }
         const queryString = queryParams.toString();
         const url = `${this.basePath}/api/ai/analyze-job-description${queryString ? `?${queryString}` : ''}`;
         return this.http.post<Array<ComplianceIssue>>(url, jobFormDTO);

src/main/webapp/app/job/job-creation-form/job-creation-form.component.html

@@ -57,6 +57,7 @@ <h1 jhiTranslate="{{ pageTitle() }}"></h1>
                       [required]="true"
                       [model]="basicInfoForm.get('title')?.value"
                       [control]="basicInfoForm.get('title') ?? undefined"
+                      [complianceError]="titleComplianceError() ?? undefined"
                     />
                   </div>
                 </div>
@@ -183,7 +184,9 @@ <h1 jhiTranslate="{{ pageTitle() }}"></h1>
                   [shouldTranslate]="true"
                   [showGenderDecoderButton]="true"
                   height="20rem"
+                  (highlightHovered)="onHighlightHovered($event)"
                 />
+                <jhi-compliance-popover [issue]="activePopoverIssue()" [x]="popoverX()" [y]="popoverY()" />
               </div>
             </div>
           </div>
@@ -208,7 +211,10 @@ <h1 jhiTranslate="{{ pageTitle() }}"></h1>
             [isGenerating]="isGeneratingDraft()"
             [isAnalyzing]="isScoreProcessing()"
             [isRewriteMode]="rewriteButtonSignal()"
+            [currentLang]="currentDescriptionLanguage()"
+            [complianceIssues]="complianceIssues()"
             (generate)="generateJobApplicationDraft()"
+            (filterComplianceCat)="onComplianceFilterChange($event)"
           />
         </aside>
       }

src/main/webapp/app/job/job-creation-form/job-creation-form.component.ts

@@ -52,6 +52,7 @@ import {
 import { AiAssistantCardComponent } from 'app/shared/components/molecules/ai-assistant-card/ai-assistant-card.component';
 import { UserShortDTORolesEnum } from 'app/generated/model/user-short-dto';
 import { ComplianceIssue, ComplianceIssueCategoryEnum } from 'app/generated/model/compliance-issue';
+import { CompliancePopoverComponent } from 'app/shared/components/molecules/ai-compliance-popover/ai-compliance-popover.component';
 
 import { JobDetailComponent } from '../job-detail/job-detail.component';
 import * as DropdownOptions from '.././dropdown-options';
@@ -103,6 +104,7 @@ type JobFormMode = 'create' | 'edit';
     ImageUploadButtonComponent,
     CheckboxComponent,
     AiAssistantCardComponent,
+    CompliancePopoverComponent,
   ],
   providers: [JobResourceApi],
 })
@@ -114,6 +116,10 @@ export class JobCreationFormComponent {
   // ═══════════════════════════════════════════════════════════════════════════
   readonly publishButtonSeverity = 'primary' as ButtonColor;
   readonly publishButtonIcon = 'paper-plane';
+  /** Width of the compliance popover, used to clamp its position within the viewport.
+   * matches the width w-72 set in ai-compliance-popover.component.html.
+   */
+  private readonly POPOVER_WIDTH = 288;
 
   // ═══════════════════════════════════════════════════════════════════════════
   // MODE & META SIGNALS
@@ -173,8 +179,8 @@ export class JobCreationFormComponent {
   /** Last successfully translated German text (used to avoid redundant translations) */
   lastTranslatedDE = signal<string>('');
 
-  /** Last analyzed description text (used to avoid redundant compliance analysis) */
-  private lastAnalyzedText = '';
+  /** Last analyzed description text per language (used to avoid redundant compliance analysis) */
+  private lastAnalyzedText: Record<string, string> = {};
 
   // ═══════════════════════════════════════════════════════════════════════════
   // AI GENERATION SIGNALS
@@ -262,6 +268,30 @@ export class JobCreationFormComponent {
   /** List of detected compliance issues to update the UI and editor highlights */
   readonly complianceIssues = signal<ComplianceIssue[]>([]);
 
+  /** The compliance issue currently shown in the popover (undefined = none is hovered). */
+  readonly activePopoverIssue = signal<ComplianceIssue | undefined>(undefined);
+
+  /** Horizontal screen position of popover. */
+  readonly popoverX = signal<number>(0);
+
+  /** Vertical screen position of popover. */
+  readonly popoverY = signal<number>(0);
+
+  /** When set, only issues of this category are highlighted in the editor. (undefined = all categories shown) */
+  readonly activeComplianceFilter = signal<string | undefined>(undefined);
+
+  /** Returns the explanation of a compliance issue whose text appears in the job title, if any. */
+  readonly titleComplianceError = computed(() => {
+    const title = (this.basicInfoForm.get('title')?.value ?? '').toLowerCase();
+    if (!title) return undefined;
+    for (const issue of this.complianceIssues()) {
+      if (issue.text && title.includes(issue.text.toLowerCase())) {
+        return issue.explanation;
+      }
+    }
+    return undefined;
+  });
+
   // ═══════════════════════════════════════════════════════════════════════════
   // FORM GROUPS
   // ═══════════════════════════════════════════════════════════════════════════
@@ -782,6 +812,33 @@ export class JobCreationFormComponent {
     this.jobDescriptionEditor()?.highlightTexts(highlights);
   }
 
+  /**
+   * Handles hover events from highlighted spans in the editor.
+   * Finds the matching compliance issue and positions the popover.
+   */
+  onHighlightHovered(event: { text: string; x: number; y: number } | undefined): void {
+    if (!event) {
+      this.activePopoverIssue.set(undefined);
+      return;
+    }
+    const lang = this.currentDescriptionLanguage();
+    const match = this.complianceIssues().find(i => i.language === lang && i.text?.toLowerCase() === event.text.toLowerCase());
+    this.activePopoverIssue.set(match);
+    this.popoverX.set(Math.min(event.x, window.innerWidth - this.POPOVER_WIDTH));
+    this.popoverY.set(event.y);
+  }
+
+  /**
+   * Handles category filter changes from the AI assistant sidebar.
+   * Filters highlights to show only the selected category, or all if cleared.
+   */
+  onComplianceFilterChange(category: string | undefined): void {
+    this.activeComplianceFilter.set(category);
+    const lang = this.currentDescriptionLanguage();
+    const filtered = category ? this.complianceIssues().filter(i => i.category === category) : this.complianceIssues();
+    this.applyHighlights(filtered, lang);
+  }
+
   // ═══════════════════════════════════════════════════════════════════════════
   // AI GENERATION METHODS
   // ═══════════════════════════════════════════════════════════════════════════
@@ -1152,7 +1209,9 @@ export class JobCreationFormComponent {
     const content = lang === 'en' ? this.jobDescriptionEN() : this.jobDescriptionDE();
     this.basicInfoForm.get('jobDescription')?.setValue(content, { emitEvent: false });
     this.jobDescriptionSignal.set(content);
-    this.jobDescriptionEditor()?.forceUpdate(content);
+    this.jobDescriptionEditor()?.forceUpdate(content, () => {
+      this.applyHighlights(this.complianceIssues(), lang);
+    });
   }
 
   // ═══════════════════════════════════════════════════════════════════════════
@@ -1239,11 +1298,15 @@ export class JobCreationFormComponent {
     this.lastTranslatedEN.set(en);
     this.jobDescriptionDE.set(de);
     this.lastTranslatedDE.set(de);
-    this.lastAnalyzedText = en;
+    this.lastAnalyzedText['en'] = en;
+    this.lastAnalyzedText['de'] = de;
 
     if (job?.genderBiasScore !== undefined) {
       this.aiScore.set(job.genderBiasScore);
     }
+    if (job?.complianceIssues) {
+      this.complianceIssues.set(job.complianceIssues);
+    }
 
     this.basicInfoForm.patchValue({
       title: job?.title ?? '',
@@ -1255,7 +1318,9 @@ export class JobCreationFormComponent {
     });
 
     this.jobDescriptionSignal.set(en);
-    this.jobDescriptionEditor()?.forceUpdate(en);
+    this.jobDescriptionEditor()?.forceUpdate(en, () => {
+      this.applyHighlights(this.complianceIssues(), 'en');
+    });
 
     this.positionDetailsForm.patchValue({
       startDate: job?.startDate ?? '',
@@ -1560,17 +1625,18 @@ export class JobCreationFormComponent {
 
     // 1) Build a fresh DTO and skip if the description hasn't changed since last analysis
     const jobForm = this.createJobDTO(JobFormDTOStateEnum.Draft);
+    const userLang = this.translate.currentLang;
     const descriptionText = lang === 'en' ? (jobForm.jobDescriptionEN ?? '') : (jobForm.jobDescriptionDE ?? '');
-    if (!descriptionText.trim() || descriptionText === this.lastAnalyzedText) {
+    if (!descriptionText.trim() || descriptionText === this.lastAnalyzedText[lang]) {
       this.isAnalyzing.set(false); // Clear flag in case caller pre-set it
       return;
     }
 
     this.isAnalyzing.set(true);
     try {
       // 2) Send the description to the analysis endpoint (persists score on the backend)
-      const compliance = await firstValueFrom(this.aiApi.analyzeJobDescriptionForCompliance(lang, jobForm));
-      this.lastAnalyzedText = descriptionText;
+      const compliance = await firstValueFrom(this.aiApi.analyzeJobDescriptionForCompliance(lang, jobForm, userLang));
+      this.lastAnalyzedText[lang] = descriptionText;
       // Keep issues from other languages, but replace all issues for the current language with the latest analysis.
       const otherLang = lang === 'en' ? 'de' : 'en';
       const existingLang = this.complianceIssues().filter(issue => issue.language === otherLang);

src/main/webapp/app/shared/components/atoms/base-input/base-input.component.ts

@@ -22,6 +22,7 @@ export abstract class BaseInputDirective<T> {
   tooltipText = input<string | undefined>(undefined);
   autofocus = input<boolean>(false);
   errorEnabled = input<boolean>(true);
+  complianceError = input<string | undefined>(undefined);
   warningText = input<string | undefined>(undefined);
   helperTextLeft = input<string | undefined>(undefined);
   helperTextRight = input<string | undefined>(undefined);
@@ -40,6 +41,7 @@ export abstract class BaseInputDirective<T> {
 
   inputState = computed(() => {
     this.formValidityVersion();
+    if (this.complianceError()) return 'invalid';
     if (!this.isTouched()) return 'untouched';
     if (this.formControl().invalid) return 'invalid';
     return 'valid';
@@ -50,6 +52,9 @@ export abstract class BaseInputDirective<T> {
     this.formValidityVersion();
     this.langChange();
 
+    // compliance error in job creation form title
+    const compliance = this.complianceError();
+    if (compliance) return compliance;
     const ctrl = this.formControl();
     const errors = ctrl.errors;
     if (!errors) return null;

src/main/webapp/app/shared/components/atoms/editor/editor.component.html

@@ -30,6 +30,10 @@
       contenteditable="false"
       (focusin)="onFocus()"
       (focusout)="onBlur()"
+      (mouseover)="onEditorMouseOver($event)"
+      (mouseout)="onEditorMouseOut($event)"
+      (focus)="onEditorMouseOver($event)"
+      (blur)="onEditorMouseOut($event)"
       #editorElem
       [style.height]="height()"
     >