Project Structure
Relevant source files
The following files were used as context for generating this wiki page:This project is a personal portfolio website built using the Hexo static site generator. It utilizes a custom theme named matrix-flow and incorporates a comprehensive, repository-based newsletter management system. The structure is divided into the core Hexo application, the theme's specific implementation, and a standalone Node.js program for newsletter functionalities, with a strong emphasis on performance optimization and automation via GitHub Actions.
The overall architecture is designed to separate concerns: content generation (Hexo), presentation (theme), and backend-like services (newsletter program). This modularity allows for independent development and maintenance of each component.
High-Level Directory Structure
The repository is organized into several key top-level directories, each serving a distinct purpose within the project's ecosystem. The main components are the Hexo site source, the theme, the build output directory, and two dedicated directories for the newsletter system.
The following diagram illustrates the main directories and their relationships.
Key Directories
| Directory | Purpose | Source |
|---|---|---|
source/ | Contains the source files for the Hexo site, including Markdown posts and pages. | _config.yml:19 |
dist/ | The output directory for the generated static site files. This is the public-facing build. | _config.yml:20 |
themes/matrix-flow/ | The custom Hexo theme used for the site's layout and styling. | _config.yml:82 |
newsletters/ | Holds the Markdown source files for individual newsletters, along with templates and archives. | newsletters/README.md:5-11 |
newsletter-program/ | A standalone Node.js application for managing newsletter composition, sending, and subscriber data. | newsletter-program/README-SUBSCRIBER-MANAGEMENT.md:12-23 |
Hexo Site Generation
The core of the portfolio is a Hexo-based static site. The main configuration is managed in _config.yml, which defines source and public directories, the theme, and deployment settings.
Sources: _config.yml, src/t.txt
Build Process
The site is generated using standard Hexo CLI commands, which clean the previous build and generate new static files into the dist/ directory.
This diagram shows the flow from source files to the final deployed site.
Sources: src/t.txt:2-6, _config.yml:86-93
The build output, as seen in the logs, includes HTML pages, CSS, JavaScript bundles, fonts, and other assets.
Sources: src/t.txt:10-93
Deployment
Deployment is configured to push the contents of the dist/ directory to a separate thomas-iniguez-visioli.github.io.git repository using a Git-based deployment strategy.
# _config.yml
deploy:
- type: git
repo:
github:
url: "https://github.com/thomas-iniguez-visioli/thomas-iniguez-visioli.github.io.git%22
token: $TOKEN
message: "chore: update build"
name: alphaleadership
email: alphaleadershipyt@protonmail.com
Sources: _config.yml:86-93
Theme Architecture (themes/matrix-flow)
The matrix-flow theme is responsible for the site's appearance and frontend logic. It has a structured layout for CSS and JavaScript, with a focus on performance optimization.
Sources: themes/matrix-flow/CSS-INTEGRATION-README.md, themes/matrix-flow/scripts/critical-css-extractor.js, themes/matrix-flow/source/js/code-splitter.js
Frontend Asset Structure
The theme organizes its assets to support modern web performance practices like critical CSS inlining and JavaScript code splitting.
themes/matrix-flow/
├── source/
│ ├── css/ # Main and conditional CSS files
│ └── js/ # JavaScript modules
├── layout/
│ └── _partial/
│ ├── critical-css.ejs # Inlined critical CSS
│ └── css-integration.ejs # Logic for CSS loading
└── scripts/
├── critical-css-extractor.js # Extracts critical CSS during build
└── css-build.js # Optimizes and minifies CSS
Sources: themes/matrix-flow/CSS-INTEGRATION-README.md:15-25, themes/matrix-flow/scripts/critical-css-extractor.js:1-5
Performance Optimization
The theme employs several strategies to improve load times:
-
Critical CSS Extraction: A script (
critical-css-extractor.js) identifies and extracts "above-the-fold" CSS rules. This critical CSS is then inlined directly into the HTML to prevent render-blocking and Flash of Unstyled Content (FOUC).
Sources: themes/matrix-flow/scripts/critical-css-extractor.js, themes/matrix-flow/scripts/critical-css.js -
Code Splitting: The
CodeSplitterclass manages the dynamic loading of JavaScript modules based on priority, dependencies, and triggers (e.g., interaction, scroll, idle). This prevents loading unnecessary JavaScript on the initial page load.
Sources: themes/matrix-flow/source/js/code-splitter.js
The following class diagram shows the structure of the CodeSplitter module manager.
The CodeSplitter registers modules with different priorities:
| Module Name | Priority | Path | Trigger |
|---|---|---|---|
viewport-manager | critical | /js/viewport-manager.js | Immediate |
matrix-animation | critical | /js/matrix.js | Immediate |
newsletter | high | /js/newsletter.js | interaction |
lazy-loader | medium | /js/lazy-loader.js | scroll |
performance-analytics | low | /js/performance-analytics.js | idle |
| Sources: themes/matrix-flow/source/js/code-splitter.js:28-63 |
Newsletter System
The project features a sophisticated newsletter system split into two parts: content management within the newsletters/ directory and a processing engine in newsletter-program/.
Newsletter Content (newsletters/)
This directory follows a "repository as a CMS" pattern. Newsletters are written in Markdown files with YAML frontmatter defining their metadata.
Sources: newsletters/README.md, newsletters/newsletter-template.md
Directory Structure:
newsletters/
├── archive/ # Archived sent newsletters
├── output/ # Generated HTML previews
├── newsletter-template.md # Template for new newsletters
└── *.md # Draft or scheduled newsletters
Sources: newsletters/README.md:5-11
Newsletter Frontmatter:
A newsletter file contains metadata crucial for its processing and sending.
| Field | Description | Status |
|---|---|---|
subject | The email subject line. | Required |
date | Display date for the newsletter. | Required |
status | The current state: draft, scheduled, or sent. | Required |
scheduled_at | ISO 8601 datetime for automatic sending. | Optional |
variables | Custom key-value pairs for template substitution. | Optional |
| Sources: newsletters/README.md:21-31, newsletters/newsletter-template.md:2-12 |
Newsletter Program (newsletter-program/)
This is a self-contained Node.js application that provides CLI tools and automation for managing subscribers and newsletters.
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md
Architecture:
The program is structured to handle core logic, CLI commands, and data storage separately.
newsletter-program/
└── src/
├── core/ # Core logic (subscribers, analytics, encryption)
├── cli/ # Command-line interface definitions
└── data/
├── subscribers.encrypted.json # Encrypted subscriber data
└── backups/ # Automatic encrypted backups
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md:12-23
Subscriber Management:
Subscriber data, particularly email addresses, is stored in an encrypted JSON file (subscribers.encrypted.json). The system uses AES-256-CBC for encryption, with the key managed via environment variables. This file-based approach avoids the need for an external database.
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md:8, 21, 98-103
Subscription and Sending Flow
The entire newsletter lifecycle, from subscription to sending, is heavily automated using GitHub Actions.
This sequence diagram illustrates the user subscription process.