Project Structure
Directory Overview
The Quantum Advantage Tracker is built using Next.js with the App Router architecture. It is configured for a static export, meaning the entire site is generated as a set of static HTML/CSS/JS files from structured JSON data.
.
├── data/ # Project "Database" (JSON files & circuit models)
├── src/
│ ├── app/ # Application routes, layouts, and pages
│ ├── components/ # Reusable UI components
│ ├── icons/ # Custom SVG icons
│ ├── lib/ # Utility functions (Tailwind merging, etc.)
│ ├── types/ # TypeScript definitions
│ └── utils.ts # Helper functions for data processing
├── public/ # Static assets (images, etc.)
└── next.config.ts # Build configuration (Static HTML export)
Routing and Page Hierarchy
The application follows the Next.js App Router conventions. Key routes are organized as follows:
| Route | File Path | Description |
| :--- | :--- | :--- |
| / | src/app/(home)/page.tsx | The landing page featuring an overview of the three pathways. |
| /participate | src/app/participate/page.tsx | Documentation on how to contribute new results and circuit models. |
| /trackers | src/app/trackers/page.tsx | Redirects to the default tracker (Observable Estimations). |
| /trackers/[pathway] | src/app/trackers/[pathway]/page.tsx | Specific dashboard for one of the three advantage pathways. |
Tracker Pathways
The project is divided into three primary pathways, each located within src/app/trackers/:
- Observable Estimations: Tracks expectation values and error bars.
- Variational Problems: Focuses on ground-state energy bounds.
- Classically Verifiable Problems: Focuses on problems with checkable witnesses.
Data-to-UI Mapping
The UI is dynamically populated by JSON files located in the root data/ directory. This allows the community to submit results via Pull Requests without modifying application code.
Submission Data
Each tracker pathway imports data from two primary JSON files:
submissions.json: Contains the experimental results, contributor information, and links to external papers.circuit-models.jsonorhamiltonians.json: Contains the definitions of the problem instances being tracked.
Utility Functions
The application uses several utilities in src/utils.ts to map this data to the frontend:
formatDate: Standardizes submission dates toYYYY-MM-DD.sortSubmissions: Ensures the latest quantum advantage claims appear at the top of the tables.getCircuitInstanceUrl: Generates direct links to the GitHub-hosted circuit files for researchers to download and verify.
// Example: Generating a link to a circuit model
const url = getCircuitInstanceUrl('observable-estimations', {
type: 'random-circuits',
path: 'n50_d20.qasm'
});
UI Component Architecture
The project utilizes a modular component system built on Tailwind CSS.
NavMenu.tsx: The global navigation bar. It includes logic to highlight the active route using theusePathnamehook.TrackerTabs.tsx: A specialized sub-navigation component used within the/trackersroute to switch between different advantage categories.SubmissionsTable.tsx: A pathway-specific component that renders the JSON data into a searchable and sortable grid.Contributors.tsx: An animated marquee on the home page that dynamically parses thesubmissions.jsonfiles to display participating organizations.
Configuration for Deployment
The site is configured for GitHub Pages deployment via next.config.ts:
const nextConfig: NextConfig = {
output: 'export', // Enables static HTML export
basePath: process.env.PAGES_BASE_PATH, // Handles sub-directory hosting
images: { unoptimized: true }, // Required for static export compatibility
};
This configuration ensures that the project remains platform-agnostic and can be hosted entirely from the repository's /docs or gh-pages branch.