Score History Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/components/ScoreHistory.tsx
• src/lib/add-to-history.tsx
• src/components/cvss-calculator/SaveScoreDialog.tsx
• src/components/CVSSGenericCalculator.tsx
• src/components/comparison-dialog.tsx
• src/lib/constants.ts
• src/components/CVSSCalculator.tsx
• src/lib/cvss/types.ts

The Score History Management system provides a comprehensive, client-side solution for saving, tracking, and analyzing CVSS scores calculated within the Quant application. All data is stored locally in the user's browser using localStorage, ensuring privacy as no information is sent to a server. The system is managed primarily through the ScoreManager component, which offers features for listing, sorting, comparing, editing, deleting, and restoring scores.

This feature allows users to maintain a persistent record of their vulnerability assessments. Key functionalities include side-by-side score comparison, data visualization through charts, and the ability to import or export the entire score history as a JSON file. The architecture is event-driven, ensuring that different parts of the application remain synchronized with the history data.

Sources: src/components/ScoreHistory.tsx:5-11, src/components/FAQAccordion.tsx:132-145, README.md:61-62

Architecture and Data Flow

The score history management process begins when a user decides to save a calculated score from the CVSSGenericCalculator. The system uses localStorage for persistence and a custom browser event (cvss-history-update) to notify components of data changes.

The following diagram illustrates the high-level data flow for saving a new score and updating the history view.

This diagram shows the flow from user action in the calculator to the final update in the score manager UI.

Sources: src/components/CVSSGenericCalculator.tsx:201-218, src/lib/add-to-history.tsx:5-24, src/components/ScoreHistory.tsx:448-462

Data Model

The core of the history system is the ScoreHistoryEntry data structure. Each time a score is saved, a new object of this type is created and stored.

The ER diagram above details the fields within a ScoreHistoryEntry.

ScoreHistoryEntry Fields

Field	Type	Description
id	string	A unique identifier generated from the current timestamp and a random string.
version	string	The CVSS version used for the calculation (e.g., "4.0", "3.1").
score	number	The final numeric score.
severity	string	The qualitative severity rating (e.g., "None", "Low", "Medium", "High", "Critical").
vectorString	string	The complete CVSS vector string representing the selected metrics.
timestamp	string	An ISO 8601 formatted string indicating when the score was saved.
name	string	A user-provided name for easy identification. Defaults to "Unnamed Score" if not provided.

Sources: src/lib/add-to-history.tsx:31-38, src/components/ScoreHistory.tsx:44-44

Core Components

The Score History Management feature is composed of several key React components and library functions that work together.

ScoreManager Component

The ScoreManager is the primary user interface for interacting with saved scores. It is responsible for rendering the list of historical entries and providing tools for their management.

Key Features:

• Data Display: Renders saved scores in a sortable and searchable table.
• State Management: Uses React hooks (useState, useMemo, useCallback) to manage the history list, user selections, sorting state, and search queries.
• CRUD Operations: Provides UI for editing entry names, deleting entries, and clearing the entire history.
• Bulk Actions: Allows users to select multiple entries to perform comparisons (ComparisonDialog) or generate aggregate charts (ChartDialog).
• Data Sync: Listens for the cvss-history-update event to reload data from localStorage whenever the history is modified elsewhere in the app.
• Import/Export: Contains logic for importing and exporting the score history as a JSON file.

Sources: src/components/ScoreHistory.tsx

addToHistory Function

This function is the single entry point for persisting a new score to the browser's localStorage. It is decoupled from the UI components.

Process:

1. Retrieves the existing history array from localStorage using the STORAGE_KEY.
2. Creates a new ScoreHistoryEntry object, adding a unique id and timestamp.
3. Prepends the new entry to the history array.
4. Truncates the array to MAX_HISTORY entries to prevent unbounded storage growth.
5. Saves the updated array back to localStorage.
6. Dispatches a CustomEvent with the name HISTORY_UPDATE_EVENT to notify other parts of the application (like ScoreManager) that the data has changed.

Sources: src/lib/add-to-history.tsx:5-24

SaveScoreDialog Component

This is a modal dialog component that prompts the user to enter a name for the score they are about to save. It is triggered from the CVSSGenericCalculator when the user initiates a save action. The entered name is passed back to the calculator, which then uses it in the call to addToHistory.

Sources: src/components/cvss-calculator/SaveScoreDialog.tsx, src/components/CVSSGenericCalculator.tsx:201-218

ComparisonDialog Component

This dialog provides a side-by-side comparison of two selected score entries. If the two scores are from the same major CVSS version (e.g., v3.0 and v3.1), it will also parse their vector strings and display a table highlighting the specific metrics that differ between them.

Sources: src/components/comparison-dialog.tsx, src/components/ScoreHistory.tsx:812-820

Key Functionalities

Data Persistence and Synchronization

The system's persistence relies on localStorage, and its components are synchronized via a custom browser event. This creates a decoupled architecture where the "writer" (addToHistory) does not need a direct reference to the "reader" (ScoreManager).

The following diagram shows this decoupled relationship.

Score Restoration

Users can restore a previously saved score back into the main calculator interface. This functionality is initiated from the ScoreManager component.

The sequence diagram below outlines the restoration process.

This event-driven flow allows the ScoreManager to trigger an action in the CVSSCalculator without a direct component dependency.

Sources: src/components/ScoreHistory.tsx:560-577, src/components/CVSSCalculator.tsx:125-141

Import and Export

The ScoreManager component provides functionality to export the entire score history to a JSON file and import scores from a similar file.

• Export: The exportHistory function serializes the current history array into a JSON string and triggers a browser download. The filename is prefixed with cvss-history-.
  Sources: src/components/ScoreHistory.tsx:579-591
• Import: The importHistory function reads a user-selected JSON file. It parses the file, validates that it's an array, and filters out any entries whose vectorString already exists in the current history to prevent duplicates. New entries are then added to the history.
  Sources: src/components/ScoreHistory.tsx:593-646

Configuration and Constants

Several constants define the behavior of the history management system. These are centralized for easy configuration.

Constant	Value	File	Description
STORAGE_KEY	cvss-score-history	src/lib/add-to-history.tsx	The key used to store the history array in localStorage.
MAX_HISTORY	50	src/lib/add-to-history.tsx	The maximum number of entries to keep in the history.
HISTORY_UPDATE_EVENT	cvss-history-update	src/lib/add-to-history.tsx	The name of the custom event dispatched when the history is modified.
UNNAMED_SCORE_NAME	Unnamed Score	src/components/ScoreHistory.tsx	Default name for a score saved without a user-provided name.
IMPORTED_SCORE_NAME	Imported Score	src/components/ScoreHistory.tsx	Default name for entries added via the import function.

Sources: src/lib/add-to-history.tsx:26-28, src/components/ScoreHistory.tsx:61, 62