Relevant source files
The following files were used as context for generating this wiki page:
This document details the execution flow that calculates the compliance score for frameworks displayed on the dashboard, specifically focusing on how the success of automated evidence collection runs is determined. The process begins when a user navigates to the dashboard page, triggering a series of data fetches and computations.
The primary goal of this flow is to assess the "strict completion" status of tasks associated with various compliance frameworks. A key part of this assessment involves verifying if any enabled automated evidence collection for a task has successfully completed its latest run. This ensures that compliance scores accurately reflect not only manual task completion but also the successful operation of integrated automation. The outcome directly impacts the compliance percentages shown to the user, providing an up-to-date view of their organization's adherence to various standards.
Step-by-step Narrative
The execution flow begins with the rendering of the dashboard page and proceeds through several layers of data fetching and computation to determine task compliance.
DashboardPage Initialization
The
DashboardPagecomponent serves as the entry point for this flow. Upon loading, it asynchronously fetches all necessary data to populate the dashboard, including user session information, organization details, and various compliance-related scores. Crucially, it retrieves a comprehensive list of tasks, including their associated controls and any configured evidence automations. This raw data is then passed down to subsequent functions for processing.Fetching Framework Compliance Scores
The
getFrameworkWithComplianceScoresfunction is called byDashboardPageto process the fetched data. Its purpose is to take the raw framework instances and tasks, and enrich them with calculated compliance scores. It iterates through eachframeworkInstanceand delegates the core computation of compliance statistics to thecomputeFrameworkStatsfunction. The function returns an array of frameworks, each augmented with its calculated compliance score. Sources: apps/app/src/app/(app)/[orgId]/frameworks/data/getFrameworkWithComplianceScores.ts:13-30Computing Framework Statistics
The
computeFrameworkStatsfunction receives a singleframeworkInstanceand the full list oftasksrelevant to the organization. It first identifies controls and policies pertinent to the given framework. It then filters the providedtasksto include only those associated with the current framework's controls. The function's critical role in this flow is to determine the number of "done tasks" by callingcountStrictlyCompletedTasks, which directly contributes to the overall compliance score calculation. Sources: apps/app/src/app/(app)/[orgId]/frameworks/lib/compute.ts:16-51Counting Strictly Completed Tasks
The
countStrictlyCompletedTasksfunction is responsible for iterating through a given array of tasks and determining how many of them meet the criteria for "strict completion." For each task, it callsisTaskStrictlyCompleteto evaluate its status. The function then returns a count of all tasks that are deemed strictly complete. Sources: apps/app/src/app/(app)/[orgId]/frameworks/lib/taskEvidenceDocumentsScore.ts:101-103Determining Strict Task Completion
The
isTaskStrictlyCompletefunction evaluates whether a single task is considered "strictly complete." It first checks if the task'sstatusis either'done'or'not_relevant'. If this condition is met, it then proceeds to callisTaskEvidenceCompleteto verify that all required evidence for the task is also complete. A task is only strictly complete if both its status indicates completion and its evidence requirements are satisfied. Sources: apps/app/src/app/(app)/[orgId]/frameworks/lib/taskEvidenceDocumentsScore.ts:96-99Checking Task Evidence Completion
The
isTaskEvidenceCompletefunction focuses specifically on the evidence requirements for a given task. It filters the task'sevidenceAutomationsto identify only those that are currentlyisEnabled. If there are no enabled automations, the task is considered to have complete evidence by default. Otherwise, it iterates through each enabled automation and callsisSuccessfulAutomationRunon its latest run. The task's evidence is considered complete only if all enabled automations have a successful run. Sources: apps/app/src/app/(app)/[orgId]/frameworks/lib/taskEvidenceDocumentsScore.ts:86-94Verifying Successful Automation Run
The
isSuccessfulAutomationRunfunction is the final step in this specific trace, directly evaluating the success of an individual evidence automation run. It takes anEvidenceAutomationRunLiteobject as input. The function returnstrueonly if all three conditions are met: the run'sstatusis'completed', itssuccessflag istrue, and itsevaluationStatusis not'fail'. If any of these conditions are not met, or if the run object itself is undefined, it returnsfalse. This granular check ensures that only truly successful automation runs contribute to a task's evidence completion. Sources: apps/app/src/app/(app)/[orgId]/frameworks/lib/taskEvidenceDocumentsScore.ts:81-84
Sequence Diagram
Flowchart
Key Observations
- Cross-module Boundaries: This flow demonstrates a clear separation of concerns across multiple modules.
page.tsxhandles initial data fetching and orchestration,data/getFrameworkWithComplianceScores.tsaggregates and prepares data for computation, andlib/compute.tsandlib/taskEvidenceDocumentsScore.tscontain the core business logic for calculating compliance and task completion. This modularity enhances maintainability and testability. - Potential Failure Points and Handling:
- Authentication/Authorization:
DashboardPageexplicitly checks for a valid session and redirects to/loginif not present. It also verifiesonboardingCompletedstatus, redirecting if onboarding is still pending. - Data Availability:
getScoresandgetControlTaskswithinDashboardPagehandle cases whereorganizationIdmight be missing from the session, returning default empty values. - Automation Run Status:
isSuccessfulAutomationRunmeticulously checks three conditions (status,success,evaluationStatus) to determine success, preventing partially or incorrectly completed automations from being counted as successful. If an automation run isundefined, it defaults tofalse. - No Enabled Automations:
isTaskEvidenceCompletegracefully handles tasks with no enabled evidence automations, considering their evidence complete by default, preventing false negatives in compliance scores.
- Authentication/Authorization:
- Performance Considerations:
cacheusage:getScoresandgetControlTasksinpage.tsxutilizecachefromreact, indicating that their results are memoized for the duration of the request, preventing redundant database calls within the same server-side render cycle.- Database Queries: The initial data fetching in
DashboardPageinvolves several database queries (e.g.,db.organization.findUnique,db.onboarding.findUnique,db.member.findFirst,db.task.findMany,db.frameworkEditorFramework.findMany,db.finding.findMany). These are optimized withselectandincludeclauses to fetch only necessary data. - Looping and Filtering: The core compliance calculation involves iterating over frameworks, controls, and tasks. While efficient, for very large datasets (thousands of tasks/controls), the nested loops could become a performance bottleneck. The use of
Mapfor deduplication incomputeFrameworkStatsis a good optimization to avoid redundant processing of tasks and policies.
On This Page
Step-by-step NarrativeDashboardPage InitializationFetching Framework Compliance ScoresComputing Framework StatisticsCounting Strictly Completed TasksDetermining Strict Task CompletionChecking Task Evidence CompletionVerifying Successful Automation RunSequence DiagramFlowchartKey Observations