This document provides a detailed overview of the QuantumVault frontend application, covering its architecture, state management, component library, and utility functions.

• Framework: React 18
• Build Tool: Vite
• Styling: Vanilla CSS (CSS Modules approach without the .module suffix)
• Icons: lucide-react
• Authentication: @react-oauth/google
• Utilities:
  • otpauth: TOTP generation/verification
  • qrcode: QR code generation for 2FA setup
  • jwt-decode: Parsing user identity from tokens

Follow these steps to set up the project locally.

• Node.js: Version 18 or higher
• npm: Version 9 or higher

1. Clone the repository:

   git clone https://github.com/securedapp-github/quantavault_front.git
   cd quantavault_front

2. Install dependencies:

   npm install

1. Create a .env file in the root directory:

   cp .env.example .env

2. Open .env and fill in your configuration:

   • VITE_GOOGLE_CLIENT_ID: Your Google OAuth Client ID.
   • VITE_API_URL: The URL of your backend API (e.g., http://localhost:5000/api).

Start the development server with Hot Module Replacement (HMR):

npm run dev

The application will be available at http://localhost:5173.

Generate a production-ready build in the dist/ directory:

npm run build

Preview the production build locally:

npm run preview

The application is structured as a single-page application (SPA) with centered global state management.

The QuantumContext acts as the "Single Source of Truth" for the application. It handles:

• Authentication State: Persisting the logged-in user and handling session timeouts.
• Data Fetching: Loading keys, policies, and audit logs from the backend API.
• CRUD Operations: Centralizing the logic for adding, updating, and deleting keys/policies.

• Dashboard.jsx: High-level overview of system health and quick action buttons.
• PQCKeys.jsx: Detailed management of post-quantum keys.
• AuthenticationKeys.jsx: Management of client authentication keys.
• Policies.jsx: Interface for creating and managing access control policies.
• AuditLogs.jsx: Advanced filtering and visualization of system logs.
• Settings.jsx: User profile management and 2FA configuration.

The application uses a modular component system:

• Layout: Sidebar, PageHeader, Card, Table.
• Forms: Input, Button, RadioGroup.
• Modals: Centralized Modal base with specific implementations like CreatePQCKeyModal, KeyDetailsModal, etc.
• Feedback: Badge, EmptyState, TwoFactorVerify.

1. User logs in via Google OAuth.
2. Frontend receives a JWT and parses user details.
3. If 2FA is enabled, the TwoFactorVerify modal is triggered.
4. Upon successful verification, the user gains access to the protected state.

1. User selects "Rotate" on a PQC key.
2. System generates a new key pair on the backend.
3. The old key version is marked as rotated.
4. Policies automatically point to the latest active version.

• State Issues: Use React DevTools to inspect the QuantumProvider state.
• API Errors: Check the Browser Console and Network tab. All API responses follow a { data: {}, error: { message: "" } } format.
• 2FA Problems: Ensure the system time on the server and client are synchronized, as TOTP is time-sensitive.