Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Quant is an intuitive, modern CVSS score calculator built as a client-side web application. Its architecture prioritizes privacy, speed, and accuracy by performing all calculations directly in the user's browser, with no data ever being sent to a server. The application is developed using the Astro framework with React for interactive UI components and TypeScript for robust type safety.
The core of the application is a pure JavaScript/TypeScript scoring engine that implements the official CVSS specifications for versions 2.0, 3.0, 3.1, and 4.0. This engine is decoupled from the UI, allowing for a clean separation of concerns. User data, such as score history, is persisted locally using the browser's localStorage, ensuring that user assessments remain private and accessible offline.
Sources: README.md:13-15, README.md:120-121, src/components/FAQAccordion.tsx:40-43, package.json:11-12
Technology Stack
The project is built on a modern web technology stack, focusing on performance and developer experience. The primary dependencies are defined in package.json.
| Technology / Library | Purpose |
|---|---|
| Astro | The core web framework used for building the static site with server-side rendering and client-side hydration. |
| React | Used for creating interactive UI components, such as the calculator interface and score manager. |
| TypeScript | Provides static typing for the entire codebase, ensuring type safety and improving code quality. |
| Tailwind CSS | A utility-first CSS framework for styling the application. |
| Radix UI | Provides a set of unstyled, accessible UI primitives for building the component library (e.g., Accordion, Tabs, Dialog). |
| Recharts | A composable charting library used for visualizing score data in the Score Manager. |
| pnpm | The package manager used for dependency management. |
Sources: package.json:2-40, README.md:85-88
High-Level Architecture
The application follows a client-side architecture where all logic is executed within the user's browser. This design choice ensures user privacy and enables full offline functionality.
The diagram below illustrates the main architectural components and their interactions.
This diagram shows that the user interacts with React components. These components use the CVSS Scoring Engine for calculations, which in turn relies on predefined metric data. The Score History Manager interacts with the browser's Local Storage to persist data.
Sources: README.md:120-121, src/components/FAQAccordion.tsx:40-48, src/components/ScoreHistory.tsx:29-31
Core Logic: CVSS Scoring Engine
The scoring engine is the heart of Quant. It is implemented in pure TypeScript and is completely self-contained, allowing it to run in any JavaScript environment.
Sources: README.md:20, src/lib/cvss/v3/scoring.ts, src/lib/cvss/v2/scoring.ts
Version-Specific Modules
The scoring logic is modularized by CVSS version, with dedicated files for each major specification. This ensures that calculations adhere strictly to the correct standard and simplifies maintenance.
- CVSS v3.x: Logic is contained in
src/lib/cvss/v3/scoring.ts. It handles both v3.0 and v3.1, with conditional logic for differences like theroundUpfunction. - CVSS v2.0: Logic is contained in
src/lib/cvss/v2/scoring.ts.
Sources: src/lib/cvss/v3/scoring.ts, src/lib/cvss/v2/scoring.ts
Calculation Flow
The calculation process for each version follows a similar pattern: metric weights are retrieved, sub-scores are calculated, and these are combined to produce the final Base, Temporal, and Environmental scores.
This flowchart shows the step-by-step process of calculating a CVSS score, from metric selection to the final score determination.
Sources: src/lib/cvss/v3/scoring.ts:468-511, src/lib/cvss/v2/scoring.ts:289-331
Key Scoring Functions
The engine uses a set of core functions to perform calculations according to the CVSS specifications.
| Function | Description | Example Source |
|---|---|---|
calculateCVSSv3Score | Orchestrates the entire scoring process for a given set of CVSS v3.x metrics. | src/lib/cvss/v3/scoring.ts:468 |
calculateBaseScore | Calculates the Base Score from the Impact and Exploitability sub-scores. | src/lib/cvss/v3/scoring.ts:271 |
calculateImpact | Calculates the Impact sub-score based on Confidentiality, Integrity, and Availability metrics. | src/lib/cvss/v3/scoring.ts:222 |
calculateExploitability | Calculates the Exploitability sub-score based on metrics like Attack Vector and Attack Complexity. | src/lib/cvss/v3/scoring.ts:246 |
getSeverityRating | Converts a numeric score into a qualitative severity rating (e.g., Low, Medium, High). | src/lib/cvss/v3/scoring.ts:254 |
generateVector | Creates the CVSS vector string from a set of metrics. | src/lib/cvss/v3/scoring.ts:399 |
Data Management and State
The application's data is managed through a combination of static definitions, TypeScript types, and browser storage.
Metric Definitions
All CVSS metric definitions, including their labels, descriptions, and options, are centralized in src/lib/cvss/metrics-data.ts. This file exports constants like cvss40Metrics, cvss3Metrics, and cvss2Metrics, which are arrays of MetricGroup objects. This approach decouples the UI from the scoring logic and makes it easy to update metric information.
The structure of these definitions is as follows:
This diagram shows the relationship between MetricGroup, MetricDefinition, and MetricOption as defined in src/lib/cvss/metrics-data.ts.
Sources: src/lib/cvss/metrics-data.ts:10-29
Type Safety
The project heavily utilizes TypeScript to ensure data consistency. The file src/lib/cvss/types.ts defines a comprehensive set of types for all CVSS versions, including:
- Interfaces for metric objects (e.g.,
CVSSv4Metrics,CVSSv3Metrics). - Types for individual metric values (e.g.,
CVSSv3AttackVector). - Interfaces for score results (e.g.,
DetailedScore,CVSSv4Score).
Sources: src/lib/cvss/types.ts
Local Storage for Score History
The "CVSS Score Manager" feature persists user-saved scores in the browser's localStorage. This functionality is primarily handled within the ScoreHistory.tsx component.
The sequence diagram below shows the flow for saving a score to the history.
This diagram illustrates how a score is saved. The UI triggers a function that reads from, updates, and writes back to the browser's Local Storage.
Sources: src/components/ScoreHistory.tsx:400-447, src/components/CVSSGenericCalculator.tsx:162-176, src/components/FAQAccordion.tsx:44-48, src/lib/constants.ts:114
UI Components
The user interface is built with React and organized into reusable components.
CVSSGenericCalculator
This is the main component for the calculator interface. It is designed to be generic and can render a calculator for any supported CVSS version by accepting a version prop.
Key responsibilities include:
- Managing the state of the selected metrics.
- Calling the appropriate scoring function from the CVSS engine whenever a metric changes.
- Displaying the real-time score, severity, and vector string.
- Rendering metric groups and options using data from
metrics-data.ts. - Handling user actions like copying the vector, sharing, and saving to history.
Sources: src/components/CVSSGenericCalculator.tsx
ScoreHistory
This component provides a full-featured interface for managing saved scores. It reads and writes to localStorage and offers the following features:
- Listing, sorting, and filtering saved scores.
- Selecting scores for comparison or charting.
- Editing entry names.
- Deleting and restoring entries.
- Importing and exporting the entire history as a JSON file.
Sources: src/components/ScoreHistory.tsx
CVSSVersionsTabs
This component renders the main tabs on the page, allowing users to switch between different CVSS versions (4.0, 3.1, 3.0, 2.0). Each tab contains a brief overview of that CVSS version's features and base metrics.
Sources: src/components/CVSSVersionsTabs.tsx
Conclusion
The architecture of Quant is thoughtfully designed for a specific purpose: providing a fast, private, and accurate CVSS calculator. The key architectural decisions—a 100% client-side model, a modular and version-agnostic scoring engine, and a reactive UI built with modern web technologies—combine to create a robust and user-friendly tool. The clear separation between the scoring logic, data definitions, and UI components makes the application maintainable and extensible.
Sources: README.md:13-22, 120-124