/thomas-iniguez-visioli/portfolio

Wiki directory

Browse AI-generated documentation for any repository.

Getting Started

Relevant source files

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

This document provides a comprehensive guide to understanding, building, and running the portfolio project. The project is a static website built with the Hexo framework and features a custom matrix-flow theme. A significant component is a repository-based newsletter management system that uses GitHub Issues and Actions for subscription and distribution.

The project is configured for deployment to GitHub Pages and includes several performance optimizations, such as critical CSS extraction and advanced code splitting. The newsletter system is a standalone Node.js program designed to integrate with the main site, handle subscriber management with encryption, and automate email composition and sending.

Project Architecture

The repository is structured into several key parts: the core Hexo site, the custom matrix-flow theme, and the newsletter-program.

Hexo Site (/): The root directory contains the main Hexo configuration (_config.yml), source content (source/), and build output (public/ or dist/).
Theme (themes/matrix-flow/): Contains all assets, layouts, and scripts specific to the site's appearance and frontend functionality. This includes performance optimization scripts and the client-side newsletter logic.
Newsletter Program (newsletter-program/): A self-contained Node.js application for managing all aspects of the newsletter, from composition and subscriber management to sending emails via external APIs.

The following diagram illustrates the high-level architecture of the project.

Generating architecture diagram...

Sources: _config.yml, themes/matrix-flow/README-newsletter.md, newsletters/README.md

Configuration

The primary configuration for the website is managed in the _config.yml file. This file controls site metadata, URL structure, deployment settings, and custom configurations for the theme and newsletter.

Key Configuration Options

Key	Description	Example Value
`title`	The title of the website.	`portfolio`
`url`	The base URL of the site.	`https://thomas-iniguez-visioli.github.io/`
`public_dir`	The directory for the generated static files.	`./dist`
`theme`	The name of the active Hexo theme.	`matrix-flow`
`newsletter`	Configuration block for the newsletter system.	`{ enabled: true, discord_webhook: ... }`
`deploy`	Settings for deploying the site, configured for GitHub Pages.	`{ type: git, repo: ... }`

Sources: _config.yml:5-40, 100-116

Newsletter Configuration

The newsletter section in _config.yml contains settings for the automated newsletter system.

# Newsletter Configuration
newsletter:
  enabled: true
  discord_webhook: ${DISCORD_WEBHOOK_URL}
  retry_attempts: 3
  timeout_ms: 5000
  rate_limit_ms: 1000

Sources: _config.yml:100-106

Building the Site

The project uses npm scripts to manage the build process. The primary command builds the static site into the directory specified by public_dir in _config.yml (which is ./dist).

The build process involves cleaning the previous build artifacts and then generating the new static files.

Generating architecture diagram...

This diagram shows the sequence of commands executed during the build process.
Sources: src/t.txt:2-7

The build log indicates that Hexo processes markdown files, generates HTML pages, and handles various assets like CSS, JavaScript, and fonts.

Sources: src/t.txt:10-89

Newsletter System

The portfolio includes a sophisticated newsletter system that is managed within the repository and automated with GitHub Actions.

Subscription Flow

The subscription process is designed for privacy and automation, using GitHub Issues as a transport mechanism.

A user fills out the newsletter subscription form on the website.
The frontend JavaScript creates a GitHub issue with the subscription details.
A GitHub Action is triggered by the new issue.
The Action processes the issue, extracts subscriber data, and encrypts the email address.
The encrypted data is stored in a secure subscriber database.
A welcome email is sent to the new subscriber via the Resend API.
The original GitHub issue is closed and scheduled for deletion to protect user privacy.

The following sequence diagram illustrates this flow.

Generating architecture diagram...

This flow is detailed in the integration tests and README files for the newsletter feature.
Sources: newsletter-program/src/tests/integration/newsletter-subscription-flow.test.js, themes/matrix-flow/README-newsletter.md:23-34

Frontend Implementation

The client-side logic is handled by themes/matrix-flow/source/js/newsletter.js. The NewsletterManager class is responsible for:

Event listeners for form submission.
Real-time and on-blur validation of email, frequency, and consent.
Enhanced email validation, including checks for disposable domains and suggestions for common typos.
Generating a GitHub issue URL with pre-filled subscription data.
Handling UI state (e.g., loading indicators, success/error messages).
Tracking analytics events for user interactions.

Sources: themes/matrix-flow/source/js/newsletter.js:8-40, 77-183, 241-285

Newsletter Composition and Management

The newsletter-program contains the backend logic and CLI for managing newsletters. Newsletters are written in Markdown files with YAML frontmatter.

Newsletter File Format

---
subject: Newsletter Title
date: 2025-10-31
status: draft|scheduled|sent
scheduled_at: 2025-11-01T10:00:00Z
variables:
  author: Newsletter Team
---

# Newsletter Content

Your markdown content here...

Sources: newsletters/README.md:14-26

The NewsletterComposer class in newsletter-program/src/core/newsletter-composer.js handles parsing these files, converting Markdown to HTML, and injecting the content and variables into an HTML email template.

Sources: newsletter-program/src/core/newsletter-composer.js:15-41, 71-96

CLI Commands

A set of CLI commands are available to manage the newsletter lifecycle.

Command	Description
`npm run newsletter create <name>`	Creates a new newsletter from a template.
`npm run newsletter preview <name>`	Generates an HTML preview of a newsletter.
`npm run newsletter schedule <name> <date>`	Schedules a newsletter for sending.
`npm run newsletter send <name>`	Sends a newsletter to all subscribers.
`npm run newsletter list`	Lists all available newsletters and their status.

Sources: newsletters/README.md:37-64

Performance Optimizations

The project implements several strategies to improve frontend performance.

Critical CSS Extraction

To speed up the initial page render and avoid a Flash of Unstyled Content (FOUC), the build process includes a script to extract critical, above-the-fold CSS.

The CriticalCSSExtractor class identifies essential CSS rules and inlines them directly into the HTML, while the remaining non-critical styles are loaded asynchronously.

The flow is as follows:

Read the main CSS file.
Filter rules based on a predefined list of criticalSelectors (e.g., html, body, .fullscreen-container, .logo-glitch).
Optimize the extracted critical CSS by minifying it.
Generate a partial template (critical-css.ejs) to be inlined in the <head> of the document.
Create a helper to load the non-critical CSS asynchronously.

Generating architecture diagram...

Sources: themes/matrix-flow/scripts/critical-css-extractor.js:15-39, 53-85, 110-125

Advanced Code Splitting

The code-splitter.js script manages the loading of JavaScript modules intelligently. It prioritizes modules based on their importance and how they are triggered.

Module Registry: Defines all available JS modules with metadata like path, priority, dependencies, and loadTrigger.
Priority-Based Loading: Modules are categorized as critical, high, medium, or low priority. Critical modules are loaded first.
Dynamic Loading: Modules can be loaded based on triggers like user interaction (interaction), scroll position (scroll), or when the browser is idle (idle).

This ensures that essential functionality is available immediately, while deferring the loading of less critical scripts to improve initial page load times.

Sources: themes/matrix-flow/source/js/code-splitter.js:8-58, 101-110

Getting Started

Relevant source files

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

Project Architecture

The repository is structured into several key parts: the core Hexo site, the custom matrix-flow theme, and the newsletter-program.

Hexo Site (/): The root directory contains the main Hexo configuration (_config.yml), source content (source/), and build output (public/ or dist/).
Theme (themes/matrix-flow/): Contains all assets, layouts, and scripts specific to the site's appearance and frontend functionality. This includes performance optimization scripts and the client-side newsletter logic.
Newsletter Program (newsletter-program/): A self-contained Node.js application for managing all aspects of the newsletter, from composition and subscriber management to sending emails via external APIs.

The following diagram illustrates the high-level architecture of the project.

Generating architecture diagram...

Sources: _config.yml, themes/matrix-flow/README-newsletter.md, newsletters/README.md

Configuration

Key Configuration Options

Key	Description	Example Value
`title`	The title of the website.	`portfolio`
`url`	The base URL of the site.	`https://thomas-iniguez-visioli.github.io/`
`public_dir`	The directory for the generated static files.	`./dist`
`theme`	The name of the active Hexo theme.	`matrix-flow`
`newsletter`	Configuration block for the newsletter system.	`{ enabled: true, discord_webhook: ... }`
`deploy`	Settings for deploying the site, configured for GitHub Pages.	`{ type: git, repo: ... }`

Sources: _config.yml:5-40, 100-116

Newsletter Configuration

The newsletter section in _config.yml contains settings for the automated newsletter system.

# Newsletter Configuration
newsletter:
  enabled: true
  discord_webhook: ${DISCORD_WEBHOOK_URL}
  retry_attempts: 3
  timeout_ms: 5000
  rate_limit_ms: 1000

Sources: _config.yml:100-106

Building the Site

The project uses npm scripts to manage the build process. The primary command builds the static site into the directory specified by public_dir in _config.yml (which is ./dist).

The build process involves cleaning the previous build artifacts and then generating the new static files.

Generating architecture diagram...

This diagram shows the sequence of commands executed during the build process.
Sources: src/t.txt:2-7

The build log indicates that Hexo processes markdown files, generates HTML pages, and handles various assets like CSS, JavaScript, and fonts.

Sources: src/t.txt:10-89

Newsletter System

The portfolio includes a sophisticated newsletter system that is managed within the repository and automated with GitHub Actions.

Subscription Flow

The subscription process is designed for privacy and automation, using GitHub Issues as a transport mechanism.

A user fills out the newsletter subscription form on the website.
The frontend JavaScript creates a GitHub issue with the subscription details.
A GitHub Action is triggered by the new issue.
The Action processes the issue, extracts subscriber data, and encrypts the email address.
The encrypted data is stored in a secure subscriber database.
A welcome email is sent to the new subscriber via the Resend API.
The original GitHub issue is closed and scheduled for deletion to protect user privacy.

The following sequence diagram illustrates this flow.

Generating architecture diagram...

Frontend Implementation

The client-side logic is handled by themes/matrix-flow/source/js/newsletter.js. The NewsletterManager class is responsible for:

Event listeners for form submission.
Real-time and on-blur validation of email, frequency, and consent.
Enhanced email validation, including checks for disposable domains and suggestions for common typos.
Generating a GitHub issue URL with pre-filled subscription data.
Handling UI state (e.g., loading indicators, success/error messages).
Tracking analytics events for user interactions.

Sources: themes/matrix-flow/source/js/newsletter.js:8-40, 77-183, 241-285

Newsletter Composition and Management

The newsletter-program contains the backend logic and CLI for managing newsletters. Newsletters are written in Markdown files with YAML frontmatter.

Newsletter File Format

---
subject: Newsletter Title
date: 2025-10-31
status: draft|scheduled|sent
scheduled_at: 2025-11-01T10:00:00Z
variables:
  author: Newsletter Team
---

# Newsletter Content

Your markdown content here...

Sources: newsletters/README.md:14-26

Sources: newsletter-program/src/core/newsletter-composer.js:15-41, 71-96

CLI Commands

A set of CLI commands are available to manage the newsletter lifecycle.

Command	Description
`npm run newsletter create <name>`	Creates a new newsletter from a template.
`npm run newsletter preview <name>`	Generates an HTML preview of a newsletter.
`npm run newsletter schedule <name> <date>`	Schedules a newsletter for sending.
`npm run newsletter send <name>`	Sends a newsletter to all subscribers.
`npm run newsletter list`	Lists all available newsletters and their status.

Sources: newsletters/README.md:37-64

Performance Optimizations

The project implements several strategies to improve frontend performance.

Critical CSS Extraction

To speed up the initial page render and avoid a Flash of Unstyled Content (FOUC), the build process includes a script to extract critical, above-the-fold CSS.

The CriticalCSSExtractor class identifies essential CSS rules and inlines them directly into the HTML, while the remaining non-critical styles are loaded asynchronously.

The flow is as follows:

Read the main CSS file.
Filter rules based on a predefined list of criticalSelectors (e.g., html, body, .fullscreen-container, .logo-glitch).
Optimize the extracted critical CSS by minifying it.
Generate a partial template (critical-css.ejs) to be inlined in the <head> of the document.
Create a helper to load the non-critical CSS asynchronously.

Generating architecture diagram...

Sources: themes/matrix-flow/scripts/critical-css-extractor.js:15-39, 53-85, 110-125

Advanced Code Splitting

The code-splitter.js script manages the loading of JavaScript modules intelligently. It prioritizes modules based on their importance and how they are triggered.

Module Registry: Defines all available JS modules with metadata like path, priority, dependencies, and loadTrigger.
Priority-Based Loading: Modules are categorized as critical, high, medium, or low priority. Critical modules are loaded first.
Dynamic Loading: Modules can be loaded based on triggers like user interaction (interaction), scroll position (scroll), or when the browser is idle (idle).

This ensures that essential functionality is available immediately, while deferring the loading of less critical scripts to improve initial page load times.

Sources: themes/matrix-flow/source/js/code-splitter.js:8-58, 101-110