Architecture Overview

Relevant source files

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

• astro.config.ts
• package.json
• src/components/astro/database/reactive-datatable.tsx
• src/content.config.ts
• src/lib/career-paths.ts
• src/pages/career-paths/[path]/data.json.ts
• src/pages/database/data-index.json.ts
• src/pages/database/data.json.ts
• scripts/screenshot.js

The CyberPath project is a modern web application designed to provide a comprehensive, community-driven database of cybersecurity certifications and career paths. Built on the Astro framework, it leverages a hybrid rendering model, combining server-side generation for static content with client-side interactivity powered by React. The architecture emphasizes performance and maintainability through a clear separation of content, data APIs, and UI components.

The core of the application is its certification database, managed as a collection of Markdown files with structured frontmatter. This content is exposed via a set of JSON API endpoints, which are consumed by a reactive, client-side datatable. This datatable provides users with fast, searchable, and paginated access to the certification data. The system is further enhanced with pre-computed search indexes using Fuse.js to ensure a responsive user experience.

Technology Stack

The project utilizes a modern web development stack, centered around Astro for the build and rendering engine. Key dependencies are managed in package.json and integrated via the Astro configuration.

Category	Technology / Library	Description	Source
Framework	Astro	The core web framework for building the site.	[package.json:17](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/package.json#L17)
UI Library	React	Used for interactive UI components, such as the reactive datatable.	[package.json:11](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/package.json#L11)
Styling	Tailwind CSS	A utility-first CSS framework for styling the application.	[package.json:13](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/package.json#L13)
Search	Fuse.js	A lightweight fuzzy-search library used for client-side and server-side searching of certifications.	[package.json:20](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/package.json#L20)
Content	MDX	Allows embedding JSX components within Markdown files, used for certification content.	[package.json:10](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/package.json#L10)
Monitoring	Sentry	Integrated for error tracking and performance monitoring, enabled in development environments.	[package.json:14](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/package.json#L14)
Automation	Puppeteer	Used in a build script to programmatically take screenshots of the application.	[package.json:34](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/package.json#L34)
Image Opt.	Sharp	Used in the screenshot script to process and optimize the captured images into WebP format.	[package.json:36](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/package.json#L36)

Sources: [package.json](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/package.json), [astro.config.ts](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/astro.config.ts)

Framework Integration

The astro.config.ts file orchestrates the integration of these technologies. The diagram below illustrates how Astro combines various plugins and tools to build the final application.

This diagram shows the central role of astro.config.ts in integrating various plugins for styling, UI, content, and tooling.
Sources: [astro.config.ts:8-26](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/astro.config.ts#L8-L26)

Content & Data Management

The application's data, primarily cybersecurity certifications, is managed using Astro's Content Collections feature. This provides a structured, file-based CMS approach.

Certification Content Schema

Certification data is defined in src/content.config.ts. Each certification is a Markdown file with a strictly typed frontmatter schema enforced by Zod.

The following diagram and table describe the structure of a certifications entry.

This ER diagram shows the fields and data types for the certifications collection.
Sources: [src/content.config.ts:7-21](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/src/content.config.ts#L7-L21)

Field	Type	Description	Required
title	string	The full title of the certification.	Yes
acronym	string	The common acronym for the certification.	Yes
last_updated_at	date	The date the certification information was last updated.	Yes
image	image	An optimized image for the certification.	Yes
reference	string	A URL to the official certification page.	Yes
aliases	string[]	An optional array of alternative names or acronyms.	No
draft	boolean	A flag to mark the entry as a draft (defaults to false).	No
career_paths	enum[]	An array of associated career paths from CareerPathsList.	Yes
price	string	The price of the certification.	Yes
currency	string	The currency for the price (e.g., "USD").	Yes

Sources: [src/content.config.ts:7-21](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/src/content.config.ts#L7-L21), [src/lib/career-paths.ts:13](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/src/lib/career-paths.ts#L13)

Career Paths

Career paths are defined as a constant array in src/lib/career-paths.ts. This list is used to categorize certifications and generate dynamic pages for each path.

• CareerPathsList: A constant array of strings containing all available career path names.
• CareerPathsData: An object mapping each career path name to its description, image, and image attribution.

Sources: [src/lib/career-paths.ts:13-24](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/src/lib/career-paths.ts#L13-L24), [src/lib/career-paths.ts:29-100](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/src/lib/career-paths.ts#L29-L100)

Data API Endpoints

The application serves its content via several server-rendered JSON endpoints. These endpoints are used by the frontend to fetch data dynamically.

Endpoint	Method	Description	Source File
/database/data.json	GET	Returns a JSON array of all certification metadata.	[src/pages/database/data.json.ts](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/src/pages/database/data.json.ts)
/database/data-index.json	GET	Returns a pre-computed Fuse.js search index for all certifications.	[src/pages/database/data-index.json.ts](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/src/pages/database/data-index.json.ts)
/career-paths/[path]/data.json	GET	Returns a JSON array of certifications filtered by the specified career path. The [path] is a kebab-cased version of the career path name.	[src/pages/career-paths/[path]/data.json.ts]()
/career-paths/[path]/data-index.json	GET	Returns a pre-computed Fuse.js search index for certifications within a specific career path.	[src/pages/career-paths/[path]/data-index.json.ts]()

Frontend Architecture

The user-facing database is powered by a single, complex React component that handles data fetching, state management, searching, and rendering.

Reactive Datatable Component

The ReactiveDatatable component, located at src/components/astro/database/reactive-datatable.tsx, is the central piece of the interactive certification database. It is marked as a client-side component with "use client";.

Data Loading and Initialization

On component mount, it fetches both the full dataset and the pre-computed search index in parallel. It also reads URL query parameters (page, query) to initialize its state.

The following sequence diagram illustrates the initialization flow:

This diagram shows how the ReactiveDatatable component loads its initial data and state from API endpoints and URL parameters.
Sources: [src/components/astro/database/reactive-datatable.tsx:172-251](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/src/components/astro/database/reactive-datatable.tsx#L172-L251)

Search and Filtering Logic

User input in the search bar updates the query state. A useMemo hook then uses the Fuse.js instance to perform a fuzzy search on the dataset. The results update the display_data and the pagination is recalculated accordingly.

This flowchart details the client-side search and filtering mechanism within the ReactiveDatatable component.
Sources: [src/components/astro/database/reactive-datatable.tsx:154-170](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/src/components/astro/database/reactive-datatable.tsx#L154-L170), [src/components/astro/database/reactive-datatable.tsx:256-259](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/src/components/astro/database/reactive-datatable.tsx#L256-L259)

Build Automation

The project includes a custom script that runs as part of the build process defined in package.json.

Screenshot Generation

The scripts/screenshot.js script uses Puppeteer to automate the process of taking a screenshot of the database page.

1. Start Server: It spawns the Astro development server (npm run dev).
2. Launch Browser: It launches a headless Chromium instance using Puppeteer.
3. Navigate & Prepare: It navigates to http://localhost:4321/database/, waits for the network to be idle, removes cookie banners, and scrolls the page.
4. Capture: It takes a screenshot of the page.
5. Optimize: It uses the Sharp library to crop the screenshot and convert it to an optimized WebP image.
6. Save: The final image is saved to the ./dist/assets directory with a generated filename.
7. Cleanup: The script kills the development server process.

This automated process ensures that a fresh, high-quality screenshot of the application's main feature is generated with every build.

Sources: [package.json:7](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/package.json#L7), [scripts/screenshot.js](https://github.com/cyberpath-HQ/Cyberpath/blob/HEAD/scripts/screenshot.js)