diff --git a/src/main/kotlin/de/fraunhofer/iem/dataprovider/kpi/metrics/MetricsService.kt b/src/main/kotlin/de/fraunhofer/iem/dataprovider/kpi/metrics/MetricsService.kt
index 53c68767568a3d1533e3a505dafce01339f27a2b..4f14f3c77a21f899c3722f7c9575e23aa3a2df84 100644
--- a/src/main/kotlin/de/fraunhofer/iem/dataprovider/kpi/metrics/MetricsService.kt
+++ b/src/main/kotlin/de/fraunhofer/iem/dataprovider/kpi/metrics/MetricsService.kt
@@ -26,12 +26,22 @@ class MetricsService(
     val ioScope = CoroutineScope(Dispatchers.IO)
 
 
+    /**
+     * Warning: Long running function!
+     *
+     * In this function we calculate the KPIs for the given project using information from the gitlab api.
+     * Therefore, we first create a repository and tool run object in the DB.
+     *
+     * Next, we asynchronously query the gitlab API and dedicated opencode tool APIs for further data.
+     * Based upon this data we calculate RAW KPIs.
+     *
+     * Once all API responses have been processes we create a KPI tree and store this to the DB.
+     *
+     * Lastly, we update the tool run with all tools, which provided results for the given repository,
+     * and store this to the DB.
+     */
     suspend fun handleRepositoryChange(repoId: Long) = defaultScope.launch {
 
-        // TODO: we need to create the tools in the db and link them to the tool run.
-        // This should probably be done on the initial server startup, based on some
-        // config properties, as the tools don't change dynamically.
-
         /**
          * Create initial db models.
          * If this fails we want the whole method to fail as we can't continue