Scientific Resources Hub Developer Guide
Scientific Resources Hub Developer Guide
This document describes the architecture, local development workflow, and deployment procedures for the Resources Hub application.
1. Architecture Overview
carlosraulps.github.io/
├── _config.yml # Jekyll site configuration
├── _data/navigation.yml # Academic navigation menu links
├── _pages/ # Academic markdown & HTML pages (about, cv, publications)
│ └── resources-archive.md # Preserved historical markdown notes (/resources/archive/)
├── resources/ # Production build output for GitHub Pages (/resources/)
│ ├── index.html # High-Density Editorial Scientific entry page
│ └── assets/ # Compiled CSS, JS, and WebGL bundle chunks
├── resources-hub/ # Isolated Vite + React + TypeScript source workspace
│ ├── src/
│ │ ├── components/ # Editorial, 3D WebGL (R3F), and interactive schematics
│ │ ├── data/ # Authentic 15-project catalog & Girão 61 allotrope data
│ │ └── theme/ # Editorial design system tokens (Ivory, Forest, Terracotta)
│ ├── vite.config.ts # Relative base ('./') building into ../resources/
│ └── package.json
└── .github/workflows/deploy.yml # Automated CI/CD workflow for GitHub Pages
2. Resources Hub Development
2.1. Prerequisites
- Node.js: v20+ or v25+
- npm: v10+ or v11+
2.2. Running Local Development Server
From the root repository:
npm run dev:resources
This boots the Vite HMR development server at http://localhost:5173/. Edits in resources-hub/src/ reflect immediately with sub-second hot reload.
2.3. Building for Production
From the root repository:
npm run build:resources
This runs TypeScript type checking (tsc) and Vite bundling. The optimized production artifacts are written directly to resources/index.html and resources/assets/.
2.4. Previewing the Production Build
npm run preview:resources
3. Carbon Atlas (2D Carbon Explorer) Integration
Carbon Atlas is Carlos’s flagship materials informatics application for exploring two-dimensional carbon allotropes beyond graphene.
3.1. Architecture & Data Provenance Protection
- Private Source Repository & Vercel Deployment: To protect unreleased ab initio crystallographic coordinates, volumetric charge density files (
*.bin,*.vti), and proprietary codebase components prior to peer-reviewed publication, Carbon Atlas is maintained in a private GitHub repository and deployed to https://2d-carbon-explorer.vercel.app/. - Public Repository Boundary:
.gitignoreexplicitly excludes2d-carbon-explorer/,database-2dgr/,*.bin, and*.vtiso that raw source code and unreleased structural files are never committed to the publiccarlosraulps.github.iorepository. - Resources Hub Integration: The Resources Hub links directly to
https://2d-carbon-explorer.vercel.app/from the navigation bar, hero banner, project catalog, and footer colophon.
4. Git & GitHub Pages Deployment
4.1. Master Branch Policy
Per user project rules, all commits and remote operations MUST target the master branch (never main).
4.2. Dual-Mode Deployment Compatibility
The website supports two deployment modes without breaking:
- GitHub Actions Deployment (Recommended):
- Configured in
.github/workflows/deploy.yml. - On push to
master, GitHub Actions builds both the Resources Hub via Vite and the Jekyll academic pages via Bundler, deploying the unified site to GitHub Pages.
- Configured in
- Standard Native Jekyll Deployment:
- Because
resources/index.htmlandresources/assets/are committed directly tomaster, standard Jekyll copies the static directory verbatim into_site/resources/. - All links in
./assets/use relative paths, ensuring zero 404s.
- Because
5. Adding New Research Repositories
To add a new research project or publication tool:
- Open
resources-hub/src/data/projects.ts. - Add a new
ProjectMetadataentry with:id: unique slugtitle: Repository or platform namecategory:'featured' | 'dft' | 'numerical' | 'ai' | 'hpc' | 'academic'primaryLanguage&languageColortechStack: string array of libraries and toolsgithubUrl: repository URLhighlights: key scientific capabilitiesschematicType: optional interactive diagram ('vasp-workflow' | 'numerical-convergence' | 'hpc-cluster' | 'latex-axiomatizer')
- Rebuild with
npm run build:resources.
