`Development`: Implement CQI calculation components for team collaboration analysis by SindiBuklaji · Pull Request #37 · ls1intum/Harmonia

SindiBuklaji · 2025-11-28T12:31:30Z

Checklist

General

I tested all changes and their related features with all corresponding user types.

Server

Important: I implemented the changes with a very good performance and prevented too many (unnecessary) and too complex database calls.
I strictly followed the principle of data economy for all database calls.
I strictly followed the server coding and design guidelines.
I documented the Java code using JavaDoc style.

Client

Important: I implemented the changes with a very good performance, prevented too many (unnecessary) REST calls and made sure the UI is responsive, even with large data (e.g. using paging).
I strictly followed the principle of data economy for all client-server REST calls.
I strictly followed the client coding and design guidelines.
I documented the React code.

Motivation and Context

This PR implements the core calculation components for the Collaboration Quality Index (CQI) system. The CQI is a key feature of Harmonia that provides instructors with quantifiable metrics to assess team collaboration quality based on Git repository analysis.

Description

This PR introduces two essential CQI calculation services that analyze different aspects of team collaboration:

ContributionBalanceCalculator:

Calculates contribution balance score (0-100) based on commit distribution among team members
Uses standard deviation formula: 100 * (1 - stdev(commit_frequency) / max_stdev)
Applies 10% penalty when any member contributes >70% of commits
Handles edge cases: single contributors, empty data, perfect balance scenarios

PairingSignalsCalculator:

Calculates pairing signals score (0-100) based on collaboration patterns
Analyzes alternation rate (team members alternating work on same files)
Analyzes co-editing rate (multiple authors editing same files within 10-minute window)
Applies 50% penalty when thresholds not met (alternation <30% or co-editing <15%)

Key Features:

Comprehensive unit tests with mock data covering all scenarios
Proper error handling and logging
Performance-optimized algorithms
Complete JavaDoc documentation
Follows Spring service architecture patterns

Files Added:

ContributionBalanceCalculator.java - Core balance calculation logic
PairingSignalsCalculator.java - Collaboration pattern analysis
ContributionBalanceCalculatorTest.java - Comprehensive test coverage
PairingSignalsCalculatorTest.java - Comprehensive test coverage

Steps for Testing

Prerequisites:

Java 25 installed
Docker running for database
Gradle build environment

Review Progress

Build project: ./gradlew clean build
Run tests: ./gradlew test
Verify code quality: ./gradlew checkstyleMain

Code Review

Code Review 1: Verify calculation algorithms match CQI specification
Code Review 2: Confirm proper handling of edge cases and error scenarios
Code Review 3: Check JavaDoc completeness and code style compliance

Manual Tests

Test 1: Perfect balance scenario - should return score of 100
Test 2: Over-contributor scenario - should apply 10% penalty
Test 3: No collaboration scenario - should return score of 0
Test 4: Threshold penalties - should apply 50% penalty for poor pairing

Test Coverage

Comprehensive unit test coverage includes:

ContributionBalanceCalculator: 7 test cases covering perfect balance, imbalance scenarios, penalties, edge cases
PairingSignalsCalculator: 8 test cases covering collaboration patterns, thresholds, time windows, edge cases
All tests use mock data to simulate realistic team collaboration scenarios
Edge cases: empty data, single contributors, extreme imbalances, time boundary conditions

Screenshots

N/A - Backend service implementation with no UI components.

github-actions · 2025-11-28T12:33:57Z

🤖 No OpenAPI or client changes needed.

github-actions · 2025-11-28T12:39:23Z

🤖 No OpenAPI or client changes needed.

github-actions · 2025-12-18T16:20:29Z

🤖 No OpenAPI or client changes needed.

… API endpoints, and enhance UI for project selection

…configuration properties

github-actions · 2025-12-18T17:55:22Z

🤖 OpenAPI spec and client code auto-updated and committed.

github-actions · 2025-12-18T18:02:41Z

🤖 No OpenAPI or client changes needed.

- Add analyzeRepository method to GitContributionAnalysisService for streamlined contribution analysis. - Implement loadBasicTeamDataStream for real-time team data fetching in Teams component. - Update RequestService to clear database before saving results and improve repository processing. - Introduce StreamResource for SSE streaming of repository analysis results. - Adjust tests to accommodate new method signatures and functionality.

…: add test logging and modify repository IDs in tests

…r obsolete directories to streamline the project structure.

…sion control

….gitignore update

- Add cqi: Double field to represent collaboration quality index - Add isSuspicious: Boolean field to flag unusual team activity - Update DTO to include server-calculated team quality metrics

- Inject ContributionBalanceCalculator dependency - Calculate CQI for each team using contribution balance scores - Update ClientResponseDTO to include cqi and isSuspicious values - Pass calculated metrics to client via streaming and database APIs

- Expose new GET /api/requestResource/getData endpoint - Retrieve pre-analyzed team data from database without re-analysis - Provides fallback for loading cached team metrics

- Accept exerciseId parameter to lookup exercise-specific git repo path - Support multiple exercises with different repository configurations - Read gitRepoPath from HarmoniaProperties based on exerciseId

- Pass gitRepoPath as parameter instead of reading from config - Support exercise-specific repository storage paths - Improve flexibility for multi-exercise scenarios

- Add detailed VCS access log debugging information - Log action types and sample entries for troubleshooting - Improve error messages with participation context

- Remove exerciseId and gitRepoPath from global Artemis config - These are now exercise-specific in harmonia.projects config - Simplifies configuration management for multiple exercises

- Add cqi property for collaboration quality index - Add isSuspicious property for team anomaly detection - Regenerated from OpenAPI schema

- Add getData() method to RequestResourceApi client - Support retrieving cached team data from server - Regenerated from updated OpenAPI schema

- Add team caching to ensure consistent metrics across views - Transform ComplexTeamData using server-provided CQI values - Remove client-side CQI recalculation, use server as source-of-truth - Update stream handler to emit ComplexTeamData with full metrics - Add teamCache to prevent duplicate transformations - Update terminology: backend server in comments

- Add useQuery hook to cache teams per exercise with infinite staleTime - Prevent unnecessary re-fetching when navigating back - Check cache before initiating SSE stream - Update React Query cache in real-time as teams stream in - Invalidate cache only on explicit reanalysis request

- Pass team object via route state from Teams page - Eliminate redundant API call that fetches fresh data - Ensures CQI metrics are consistent between list and detail views - Simplify component by removing useQuery and loading states

github-actions · 2025-12-18T21:19:00Z

🤖 OpenAPI spec and client code auto-updated and committed.

github-actions · 2025-12-18T21:21:22Z

🤖 No OpenAPI or client changes needed.

sindiibb added 2 commits November 25, 2025 00:25

Implement ContributionBalanceCalculator (part 1) for calculating CQI

1ac886b

Implement PairingSignalsCalculator for CQI and add unit tests

28491a6

SindiBuklaji requested review from Cathy0123456789, Predixx and az108 November 28, 2025 12:31

chore: formatting issues

d83e158

SindiBuklaji changed the title ~~Feature/cqi calculation~~ ´Development´: Implement CQI calculation components for team collaboration analysis Dec 4, 2025

SindiBuklaji changed the title ~~´Development´: Implement CQI calculation components for team collaboration analysis~~ Development: Implement CQI calculation components for team collaboration analysis Dec 4, 2025

SindiBuklaji and others added 2 commits December 4, 2025 22:18

fix:pipeline error

dc164f1

Merge main into feature/cqi-calculation

e720000

Predixx and others added 4 commits December 18, 2025 17:58

Add startup scripts for React, PostgreSQL, and Spring Boot servers

23b50ad

Implement project management features: add project properties, update…

d13129b

… API endpoints, and enhance UI for project selection

fix: AnalysisResource and RequestResource with correct endpoints and …

ec668c2

…configuration properties

chore: update OpenAPI spec and generated client

1215ca2

Predixx and others added 11 commits December 18, 2025 19:03

Enhance test configurations and update repository fetching parameters…

80a5ccb

…: add test logging and modify repository IDs in tests

Remove multiple subprojects from the repository, cleaning up unused o…

64bd16b

…r obsolete directories to streamline the project structure.

Add 'repos/' to .gitignore to exclude repository directories from ver…

4b22646

…sion control

Update git-repo-path comment in application.yml to clarify usage and …

32abecb

….gitignore update

Merge fix-not-working-everything into feature/cqi-calculation

26299c9

feat: Add CQI and isSuspicious fields to ClientResponseDTO

9297b33

- Add cqi: Double field to represent collaboration quality index - Add isSuspicious: Boolean field to flag unusual team activity - Update DTO to include server-calculated team quality metrics

feat: Add getData endpoint to RequestResource

bec3850

- Expose new GET /api/requestResource/getData endpoint - Retrieve pre-analyzed team data from database without re-analysis - Provides fallback for loading cached team metrics

feat: Add exerciseId parameter to cloneTeamRepository

d359273

- Accept exerciseId parameter to lookup exercise-specific git repo path - Support multiple exercises with different repository configurations - Read gitRepoPath from HarmoniaProperties based on exerciseId

refactor: Add gitRepoPath parameter to GitOperationsService

3e6a81e

- Pass gitRepoPath as parameter instead of reading from config - Support exercise-specific repository storage paths - Improve flexibility for multi-exercise scenarios

sindiibb and others added 8 commits December 18, 2025 22:01

chore: Improve logging in ArtemisClientService

78224d4

- Add detailed VCS access log debugging information - Log action types and sample entries for troubleshooting - Improve error messages with participation context

config: Remove redundant exercise configuration from app properties

e368437

- Remove exerciseId and gitRepoPath from global Artemis config - These are now exercise-specific in harmonia.projects config - Simplifies configuration management for multiple exercises

chore: Update ClientResponseDTO type definitions

a50a94d

- Add cqi property for collaboration quality index - Add isSuspicious property for team anomaly detection - Regenerated from OpenAPI schema

chore: Update RequestResourceApi generated code

b5ff4c4

- Add getData() method to RequestResourceApi client - Support retrieving cached team data from server - Regenerated from updated OpenAPI schema

chore: update OpenAPI spec and generated client

11998c9

SindiBuklaji closed this Dec 18, 2025

Predixx deleted the feature/cqi-calculation branch January 19, 2026 19:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

`Development`: Implement CQI calculation components for team collaboration analysis#37

`Development`: Implement CQI calculation components for team collaboration analysis#37
SindiBuklaji wants to merge 28 commits intomainfrom
feature/cqi-calculation

SindiBuklaji commented Nov 28, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Nov 28, 2025

Uh oh!

github-actions bot commented Nov 28, 2025

Uh oh!

github-actions bot commented Dec 18, 2025

Uh oh!

github-actions bot commented Dec 18, 2025

Uh oh!

github-actions bot commented Dec 18, 2025

Uh oh!

github-actions bot commented Dec 18, 2025

Uh oh!

github-actions bot commented Dec 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

SindiBuklaji commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

General

Server

Client

Motivation and Context

Description

Steps for Testing

Prerequisites:

Review Progress

Code Review

Manual Tests

Test Coverage

Screenshots

Uh oh!

github-actions bot commented Nov 28, 2025

Uh oh!

github-actions bot commented Nov 28, 2025

Uh oh!

github-actions bot commented Dec 18, 2025

Uh oh!

github-actions bot commented Dec 18, 2025

Uh oh!

github-actions bot commented Dec 18, 2025

Uh oh!

github-actions bot commented Dec 18, 2025

Uh oh!

github-actions bot commented Dec 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

SindiBuklaji commented Nov 28, 2025 •

edited

Loading