Project and Directory Structure

Relevant source files

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

• README.md
• package.json
• src/components/CVSSGenericCalculator.tsx
• src/components/CVSSVersionsTabs.tsx
• src/components/Footer.tsx
• src/lib/constants.ts
• src/lib/cvss/metrics-data.ts
• src/lib/cvss/types.ts
• src/lib/cvss/v2/scoring.ts
• src/lib/cvss/v3/scoring.ts
• src/lib/cvss/v4/scoring.ts
• src/lib/embed-chart.ts
• src/components/FAQAccordion.tsx

The Quant project is a modern CVSS score calculator built with Astro and React. Its structure emphasizes a clear separation between the core scoring logic and the user interface, ensuring the calculation engine is framework-agnostic and portable. All data processing is performed client-side, with no server-side backend for calculations.

The project is organized to support multiple CVSS versions (v2.0, v3.0, v3.1, and v4.0) through a modular and versioned library structure. The UI is composed of reusable React components that consume the scoring engine's functions and data definitions. This design facilitates maintenance, testing, and future updates to CVSS standards.

Sources: README.md, package.json, src/components/CVSSGenericCalculator.tsx

High-Level Directory Structure

The repository follows a standard structure for a modern web application, with distinct directories for source code, assets, and configuration.

This diagram shows the main directories and key files within the project.

Sources: package.json, src/components/CVSSGenericCalculator.tsx, src/lib/cvss/v4/scoring.ts, README.md

Project Configuration

Project metadata, dependencies, and scripts are managed in package.json.

Sources: package.json

Dependencies

The project relies on the Astro framework with React for building interactive UI components.

Dependency	Version	Description
astro	^5.16.6	The core web framework.
@astrojs/react	^4.4.2	Astro integration for React components.
react	^19.2.3	A JavaScript library for building user interfaces.
tailwindcss	^4.1.18	A utility-first CSS framework.
@radix-ui/react-*	various	A collection of unstyled, accessible UI components.
recharts	^3.6.0	A composable charting library built on React components.
typescript	^8.51.0	A typed superset of JavaScript.

Sources: package.json:10-33

Scripts

The package.json file defines several scripts for development, building, and code quality checks.

Command	Action
pnpm dev	Start local dev server at localhost:4321.
pnpm build	Build production site to ./dist/.
pnpm preview	Preview build locally before deploying.
pnpm lint	Run ESLint and code quality checks.

Sources: README.md:126-133, package.json:5-9

Source Code (src/)

The src/ directory contains all the application's source code, organized by function into subdirectories.

Components (src/components/)

This directory houses the reusable React components that form the user interface.

• CVSSGenericCalculator.tsx: The main component that orchestrates the entire calculator functionality. It manages state for metrics, calculates scores in real-time, and handles user interactions. It dynamically loads configuration and scoring functions based on the selected CVSS version.
• CVSSVersionsTabs.tsx: A tabbed interface allowing users to switch between different CVSS versions (4.0, 3.1, 3.0, 2.0).
• ScoreCard.tsx: A sticky component that displays the calculated score, severity, and vector string. It also contains the export menu.
• FAQAccordion.tsx: An accordion component that answers frequently asked questions about CVSS and the Quant tool.
• Footer.tsx: The application footer containing links to resources, community pages, and legal information.

The following diagram illustrates the relationship between the main calculator components.

This diagram shows how CVSSGenericCalculator acts as a central hub, interacting with other UI components and the underlying scoring logic.

Sources: src/components/CVSSGenericCalculator.tsx, src/components/CVSSVersionsTabs.tsx, src/components/FAQAccordion.tsx, src/components/Footer.tsx

Library (src/lib/)

This directory contains the core business logic, type definitions, constants, and utility functions. It is designed to be independent of the UI framework.

CVSS Scoring Engine (src/lib/cvss/)

This is the heart of the application, containing the complete implementation for scoring all supported CVSS versions.

• types.ts: Defines all TypeScript types for CVSS metrics, scores, and version-specific data structures (e.g., CVSSv4Metrics, CVSSv3Score). This ensures type safety across the application.
• metrics-data.ts: Contains comprehensive definitions for all metrics across all CVSS versions. This includes labels, descriptions, and options for each metric, which are used to dynamically render the calculator's UI. It also includes a getSeverityRating function to map scores to severity levels and colors.
• v2/scoring.ts, v3/scoring.ts, v4/scoring.ts: Each file provides a complete, self-contained scoring engine for its respective CVSS version. They implement the official formulas and lookup tables as defined by FIRST.org. Each module exports key functions:
  • calculateCVSS...Score: The main function to compute the score from a metrics object.
  • generateVector: Creates a CVSS vector string from a metrics object.
  • parseVector: Parses a vector string back into a metrics object.
  • createDefaultMetrics: Provides a default set of metrics.

The diagram below shows the dependencies within the CVSS scoring module.

This diagram shows that the generic calculator component calls the appropriate version-specific scoring function, which in turn relies on the shared types.ts definitions.

Sources: src/lib/cvss/types.ts, src/lib/cvss/metrics-data.ts, src/lib/cvss/v2/scoring.ts, src/lib/cvss/v3/scoring.ts, src/lib/cvss/v4/scoring.ts

Other Utilities

• constants.ts: A centralized file for application-wide constants, such as severity color maps, chart default settings, UI text, and embeddable iframe parameters. This avoids magic strings and numbers in the codebase.
• embed-chart.ts: Contains the generateEmbeddableChartHTML function, which creates a self-contained HTML and JavaScript snippet for embedding a chart of CVSS score distributions on external websites.

Sources: src/lib/constants.ts, src/lib/embed-chart.ts

Data Flow: CVSS Score Calculation

The process of calculating a CVSS score is initiated by user interaction in the CVSSGenericCalculator component and flows through the src/lib/cvss module.

This sequence diagram illustrates the real-time score update mechanism. A user's selection updates the component's state, which triggers a recalculation using the appropriate scoring engine and updates the UI.

Sources: src/components/CVSSGenericCalculator.tsx:162-171, 273-298

Conclusion

The Quant project is architected with a strong separation of concerns. The core CVSS calculation logic is isolated in the src/lib/cvss directory, making it portable and easy to maintain. The user interface, built with React and Astro, is a reactive consumer of this logic. This modular structure allows for independent updates to the UI and the scoring engines, and it simplifies the process of supporting new CVSS versions or integrating the scoring logic into other applications.

Sources: README.md, package.json, src/components/CVSSGenericCalculator.tsx