Project Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:CertDb (CyberPath) is a web application designed to be a comprehensive, public database of cybersecurity certifications. The project is built as a static site using the Astro framework, which allows for a fast, content-focused user experience. It leverages modern web technologies like React for interactive components, Tailwind CSS for styling, and TypeScript for type safety. The architecture is centered around Astro's content collections for managing certification data and generating static JSON API endpoints for consumption by the frontend.
The core of the application is a searchable and filterable database of certifications. Data is stored in Markdown files and exposed via statically generated JSON files. The frontend, a mix of Astro and React components, fetches this data to provide a dynamic and reactive user interface for exploring certifications and career paths.
Core Frameworks and Technologies
The project is built on a modern JavaScript stack, with Astro at its core. This choice facilitates a static-first architecture, where pages are pre-rendered at build time for optimal performance.
- Astro: The primary web framework used for building the site. It's configured for static site generation (
output: "static"). - React: Used for creating interactive UI components, such as the main data table. The
@astrojs/reactintegration allows seamless embedding of React components within Astro pages. - Tailwind CSS: A utility-first CSS framework used for styling the entire application. It is integrated via
@astrojs/tailwind. - TypeScript: Provides static typing for the entire codebase, enhancing developer experience and code quality.
- Fuse.js: A lightweight fuzzy-search library used for client-side searching of certifications.
Sources: astro.config.ts:25, package.json:11-25
Key Dependencies
The following table summarizes the main dependencies that define the project's technical stack.
| Dependency | Version | Description |
|---|---|---|
astro | ^5.8.0 | The core static site generator framework. |
@astrojs/react | ^4.3.0 | Astro integration for using React components. |
@astrojs/tailwind | ^6.0.2 | Astro integration for Tailwind CSS. |
@astrojs/mdx | ^4.3.0 | Astro integration for MDX support. |
react | ^18.3.1 | A JavaScript library for building user interfaces. |
tailwindcss | ^3.4.17 | A utility-first CSS framework. |
fuse.js | ^7.1.0 | Lightweight fuzzy-search library. |
typescript | ^5.8.3 | A typed superset of JavaScript. |
Sources: package.json:11-25
Astro Configuration
The astro.config.ts file defines the core behavior of the Astro build. It is configured to generate a static site hosted at https://certdb.cyberpath-hq.com.
// astro.config.ts
export default defineConfig({
site: "https://certdb.cyberpath-hq.com",
base: `/`,
trailingSlash: `ignore`,
integrations: [
tailwind({
nesting: true,
}),
react(),
sitemap(),
mdx({
extendMarkdownConfig: true,
gfm: true,
}),
],
build: {
assets: "assets",
},
output: "static",
});
Key configurations include:
output: "static": Specifies that Astro should build a fully static site.integrations: Includes Tailwind CSS, React, Sitemap generation, and MDX support.site: Sets the base URL for the production site, used for generating sitemaps and canonical URLs.
Sources: astro.config.ts:10-26
Content and Data Management
Certification data is managed using Astro's Content Collections feature, which provides a structured way to handle local content files (Markdown/MDX).
Certification Schema
A certifications collection is defined in src/content.config.ts. Each certification is a Markdown file in src/content/certifications/ with frontmatter that must adhere to a specific Zod schema. This ensures data consistency across all entries.
The diagram below illustrates the schema for the certifications collection.
This diagram shows the fields defined for each certification entry.
Sources: src/content.config.ts:6-21
The schema is defined as follows:
| Field | Type | Description |
|---|---|---|
title | z.string() | The full title of the certification. |
acronym | z.string() | The acronym for the certification. |
last_updated_at | z.date() | The date the certification information was last updated. |
image | image() | An optimized image for the certification. |
reference | z.string() | A URL to the official certification page. |
aliases | z.array(z.string()).optional() | Alternative names or acronyms. |
draft | z.boolean().default(false) | Marks the entry as a draft, hiding it from production builds. |
career_paths | z.array(z.enum(CareerPathsList)) | An array of associated cybersecurity career paths. |
price | z.string() | The price of the certification. |
currency | z.string() | The currency for the price. |
Sources: src/content.config.ts:10-20, src/lib/career-paths.ts:17-27
API Endpoints & Data Flow
The application generates several static JSON files at build time that act as a read-only API for the frontend. This approach avoids the need for a live server and database, making the site fast and scalable.
Static API Generation
Astro's file-based routing is used to create API endpoints. Files ending in .json.ts within the src/pages/ directory generate JSON files.
- /database/data.json: This endpoint returns an array of all certification metadata. It is generated by
src/pages/database/data.json.ts, which reads from the Astro content collection. - /database/data-index.json: This endpoint provides a pre-built search index for Fuse.js. It is generated by
src/pages/database/data-index.json.tsto speed up the initialization of the search functionality on the client. - /career-paths/[path]/data.json: These are dynamic endpoints for each career path (e.g.,
/career-paths/penetration-tester/data.json). They return a filtered list of certifications relevant to that path. - /career-paths/[path]/data-index.json: Similar to the main data index, these endpoints provide pre-built search indexes for each specific career path page.
Sources: src/pages/database/data.json.ts, src/pages/database/data-index.json.ts, src/pages/career-paths/[path]/data.json.ts, src/pages/career-paths/[path]/data-index.json.ts
Frontend Data Fetching
The ReactiveDatatable React component is responsible for fetching and displaying certification data. On component mount, it fetches both the full dataset (data.json) and the pre-computed Fuse.js index (data-index.json).
The following sequence diagram illustrates the data loading process for the main database page.
This flow shows how the component fetches all necessary data in parallel to initialize its state and provide a reactive experience.
Sources: src/components/astro/database/reactive-datatable.tsx:162-214
Frontend Architecture
The frontend is a hybrid of static Astro components and interactive React components.
ReactiveDatatable Component
This is the central UI component for displaying the certification database. It is located at src/components/astro/database/reactive-datatable.tsx.
Its key responsibilities include:
- State Management: Uses
useStateanduseEffecthooks to manage loading state, errors, data, search queries, and pagination. - Data Fetching: Fetches certification data and the search index from the static JSON endpoints.
- Searching: Filters data based on user input using the initialized Fuse.js instance.
- Pagination: Calculates and displays pagination controls, slicing the displayed data based on the current page.
- Rendering: Renders the data in a
Tablecomponent, with columns for certification details, career paths, and a link to more details.
The component is designed to be self-contained, handling all its logic internally after being mounted on an Astro page.
Sources: src/components/astro/database/reactive-datatable.tsx
Search Functionality
Client-side search is implemented using Fuse.js. To optimize performance, the search index is pre-computed during the build process and served as a static JSON file.
The search flow is as follows:
This diagram shows how pre-computing the index at build time allows for a fast and efficient client-side search experience.
Sources: src/components/astro/database/reactive-datatable.tsx:143-156, src/pages/database/data-index.json.ts:9-13
Build and Deployment
The project is configured for static deployment. The build process is defined by the scripts in package.json.
Build Scripts
| Script | Command | Description |
|---|---|---|
dev | astro dev | Starts the local development server. |
build | astro check && astro build && ... && node ./scripts/screenshot.js | Type-checks the code, builds the static site, and runs the screenshot script. |
preview | astro preview | Serves the built static site locally for previewing. |
Sources: package.json:5-9
Build Process Flow
The build script orchestrates a multi-step process to generate the final production assets.
This diagram outlines the steps executed during a production build, from type checking and static site generation to the custom post-build step of taking a screenshot of the database page.
Sources: package.json:7, astro.config.ts:25, scripts/screenshot.js
The screenshot.js script is a notable part of the build. It uses Puppeteer to launch a headless browser, navigate to the running application, and take a screenshot of the database page. This screenshot is then optimized using Sharp and saved, likely for use in social media previews or documentation.
Sources: scripts/screenshot.js:1-12
Summary
The architecture of CertDb is a well-considered implementation of a modern static site. By leveraging Astro for static generation, React for targeted interactivity, and a content-driven approach with Astro's Content Collections, the project achieves high performance and maintainability. The generation of static JSON APIs and pre-built search indexes at build time are key optimizations that ensure a fast and responsive user experience without the overhead of a traditional backend server. This static-first approach makes the application robust, scalable, and easy to deploy.