Local Development Setup

Relevant source files

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

• README.md
• package.json
• pnpm-workspace.yaml
• src/components/CVSSGenericCalculator.tsx
• src/components/ScoreHistory.tsx
• src/lib/cvss/v3/scoring.ts
• src/lib/constants.ts

This document provides a comprehensive guide for setting up and running the Quant project in a local development environment. Quant is an intuitive, modern CVSS score calculator built with Astro and React, featuring pure JavaScript scoring logic. The application is designed to be fully client-side, with no server-side processing for core features.

Setting up a local environment is essential for contributing to the project, whether it's fixing bugs, adding new features, or improving the user interface. This guide covers prerequisites, installation, project structure, and available development commands.

Sources: README.md:11-15, README.md:118-120, src/components/FAQAccordion.tsx:32-35

1. Prerequisites

Before you begin, ensure you have the following software installed on your machine:

• Git: For cloning the repository.
• Node.js: As the runtime environment for the project.
• pnpm: As the package manager for installing dependencies.

Sources: README.md:130-133

2. Installation

The installation process involves cloning the repository and installing the necessary dependencies using pnpm.

This diagram illustrates the initial setup flow.

Follow these steps to get the project running locally:

1. Clone the repository:

   git clone https://github.com/cyberpath-HQ/Quant.git
   

2. Navigate into the project directory:

   cd Quant
   

3. Install dependencies:

   pnpm install
   

This command reads the package.json file and installs all the required dependencies for the project.

Sources: README.md:128-136, package.json:4-8

3. Project Structure & Key Technologies

The project is built using the Astro framework with React for UI components. It is a client-side application, meaning all calculations and data storage happen within the user's browser.

• Framework: Astro (astro)
• UI Components: React (@astrojs/react, react, react-dom)
• Styling: Tailwind CSS (tailwindcss)
• UI Primitives: Radix UI (@radix-ui/*) and lucide-react for icons.
• Data Persistence: User data, such as score history, is stored in the browser's localStorage. The key for this storage is defined in src/lib/add-to-history.ts and used within the ScoreManager component.

Sources: README.md:15, package.json:10-36, src/components/ScoreHistory.tsx:415-420, src/components/FAQAccordion.tsx:39-46

Key Dependencies

The following table summarizes the main dependencies used in the project.

Category	Dependency	Description
Framework	astro	The web framework for building the application.
	@astrojs/react	Astro integration for using React components.
UI	react / react-dom	Library for building user interfaces.
	tailwindcss	A utility-first CSS framework for styling.
	@radix-ui/*	A set of unstyled, accessible UI primitives.
	recharts	A composable charting library built on React components.
	lucide-react	A library of simply beautiful open-source icons.
Utilities	dayjs	A minimalist JavaScript library for parsing, validating, and displaying dates.
	radash	A functional utility library for JavaScript.
	sonner	An opinionated toast component for React.

Sources: package.json:10-36

4. Development Commands

The package.json file defines several scripts for common development tasks. These are run from the root of the project using pnpm.

This diagram shows the typical development lifecycle using the available commands.

Available Scripts

Command	Action
pnpm install	Install dependencies.
pnpm dev	Starts the local development server at http://localhost:4321.
pnpm build	Builds the production-ready site to the ./dist/ directory.
pnpm preview	Previews the production build locally before deploying.
pnpm astro ...	Runs Astro CLI commands directly.
pnpm lint	Runs ESLint for code quality and style checks.

To start the development server:

pnpm dev

After running this command, you can access the application in your browser at http://localhost:4321.

Sources: README.md:138-150, package.json:5-8

5. Core Application Logic

The core logic of the CVSS calculator is separated from the UI components, promoting a clean architecture.

• Scoring Engines: The scoring algorithms for each CVSS version are implemented in pure TypeScript. For example, the logic for CVSSv3.x is located in src/lib/cvss/v3/scoring.ts. These files contain the mathematical formulas, constants, and weightings as defined by the official specifications.
• Metric Definitions: All data related to CVSS metrics, including their labels, descriptions, and options, is centralized in src/lib/cvss/metrics-data.ts. This file is the single source of truth for the UI when rendering metric selection controls.
• UI Components: The main calculator interface is a generic React component, CVSSGenericCalculator, found in src/components/CVSSGenericCalculator.tsx. This component dynamically renders the correct metrics and uses the appropriate scoring engine based on the selected CVSS version.

This separation allows developers to work on the scoring logic independently of the user interface.

Sources: src/lib/cvss/v3/scoring.ts, src/lib/cvss/metrics-data.ts, src/components/CVSSGenericCalculator.tsx