/thomas-iniguez-visioli/portfolio

Wiki directory

Browse AI-generated documentation for any repository.

Home

Relevant source files

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

The Home page serves as the main entry point to the portfolio, which is a static website built using the Hexo framework and a custom theme named matrix-flow. The site features a distinct "Matrix" aesthetic with glitch text effects and a scan-line overlay. A key feature integrated into the home page is a comprehensive, privacy-focused newsletter subscription system that leverages GitHub Issues and GitHub Actions for automation.

The architecture is designed for performance, utilizing techniques like critical CSS inlining to ensure fast initial rendering. The project is structured into the main Hexo site configuration, the matrix-flow theme, and a separate newsletter-program for backend processing and management.

Site Architecture

The portfolio is a static site generated by Hexo. The core configuration is managed in the root _config.yml file, which defines site metadata, URL structure, and the theme.

Framework: Hexo
Theme: matrix-flow
Deployment: Git-based deployment to GitHub Pages.

Sources: _config.yml:83, _config.yml:87-94

Build Process

The Hexo build process generates all static assets, including HTML, CSS, and JavaScript files, into the ./dist directory. This process involves rendering Markdown content, applying the matrix-flow theme templates, and processing assets. Build logs indicate the generation of numerous CSS and JS files, which are then served statically.

The diagram below illustrates the high-level build and deployment flow.

Generating architecture diagram...

This diagram shows how Hexo combines source files and the theme to produce static assets, which are then deployed.
Sources: _config.yml:18, src/t.txt

Frontend & Layout

The visual presentation is defined by the matrix-flow theme, which implements a "Matrix"-inspired design.

Visual Style

The theme uses a dark background, green text, and a monospace font to create a terminal-like feel. Key visual elements include:

A fixed canvas (#matrix-canvas) for a falling characters background effect.
A scan-line overlay animation to mimic an old CRT monitor.
A "glitch" text effect on the main logo.

These styles are defined in the main stylesheet.

Sources: themes/matrix-flow/source/css/style.css:5-23, themes/matrix-flow/source/css/style.css:91-155

Layout System

The theme employs a responsive, full-screen layout using CSS Grid. The main layout containers are:

.fullscreen-container: A flex container that fills the viewport.
.responsive-grid: A CSS Grid that organizes the header, main content, sidebar, and footer.

The grid layout adapts to different screen sizes using media queries, ensuring a consistent experience on desktop, tablet, and mobile devices.

Sources: themes/matrix-flow/source/css/style.css:61-89, themes/matrix-flow/tests/fullscreen-layout-performance.test.js:100-106

Performance Optimization: Critical CSS

To optimize the First Contentful Paint (FCP), the project uses a script to extract "critical" CSS—styles needed to render the above-the-fold content. This critical CSS is then inlined directly into the HTML <head>. The remaining non-critical styles are loaded asynchronously.

The CriticalCSSExtractor class identifies critical rules based on a predefined list of selectors, such as html, body, .fullscreen-container, and .logo-glitch.

The extraction process is as follows:

Generating architecture diagram...

This diagram shows the process of separating and inlining critical CSS for faster page loads.
Sources: themes/matrix-flow/scripts/critical-css-extractor.js, themes/matrix-flow/scripts/critical-css.js

Newsletter System

A major feature of the portfolio is its unique newsletter subscription system. It is designed to be secure and automated, using GitHub Issues as a transport mechanism instead of a traditional backend database.

Configuration

The newsletter feature is enabled and configured in both the main _config.yml and the theme's themes/matrix-flow/_config.yml.

Parameter	Description	Source File
`enabled`	Toggles the newsletter feature on or off.	`_config.yml:71`
`discord_webhook`	URL for sending notifications to Discord.	`_config.yml:72`
`github_owner`	The GitHub username or organization that owns the repository.	`themes/matrix-flow/_config.yml:14`
`github_repo`	The name of the repository where subscription issues will be created.	`themes/matrix-flow/_config.yml:15`
`use_github_redirect`	If `true`, redirects the user to GitHub to create the issue.	`themes/matrix-flow/_config.yml:18`
`position`	Determines where the newsletter widget is displayed (`sidebar`, `footer`).	`themes/matrix-flow/_config.yml:24`

Subscription Flow

The end-to-end subscription process is entirely automated, starting from the user's interaction with the form on the website.

The following sequence diagram illustrates the complete flow from form submission to receiving a welcome email.

Generating architecture diagram...

This diagram outlines the automated steps involved in processing a new newsletter subscription.
Sources: themes/matrix-flow/source/js/newsletter.js:335-350, newsletter-program/src/tests/integration/newsletter-subscription-flow.test.js, newsletters/README.md

Frontend Subscription (`newsletter.js`)

The client-side logic is managed by the NewsletterManager class in themes/matrix-flow/source/js/newsletter.js. Its primary responsibilities are:

Event Handling: Listens for form submission and input changes.
Real-time Validation:
- Validates the email format using a regex.
- Checks for common domain typos (e.g., gamil.com instead of gmail.com).
- Blocks disposable email addresses.
- Ensures the consent checkbox is ticked.
State Management: Manages form state, including submission status and validation errors, and disables the submit button accordingly.
GitHub Issue Generation: On successful validation, it constructs a URL to create a new GitHub issue. The user is redirected to this URL to complete the submission. The issue body is pre-filled with the form data in a structured format.

The handleSubmit function orchestrates this process.

// A simplified view of the form data collection and issue body generation
collectFormData() {
    const email = document.getElementById('newsletter-email').value.trim();
    const frequency = document.getElementById('newsletter-frequency').value;
    const topics = Array.from(document.querySelectorAll('input[name="topics"]:checked')).map(cb => cb.value);
    
    return { email, frequency, topics, /* ... */ };
}

generateIssueBody(formData) {
    // ...
    return `### Email Address\n\n${formData.email}\n\n### Newsletter Frequency\n\n${formData.frequency}\n\n...`;
}

Sources: themes/matrix-flow/source/js/newsletter.js:123-189, themes/matrix-flow/source/js/newsletter.js:253-311, themes/matrix-flow/source/js/newsletter.js:380-413

Backend Processing and Content

The newsletter-program directory contains the tools for managing newsletters and subscribers.

Newsletter Composition

Newsletters are written in Markdown with YAML frontmatter. The NewsletterComposer class is responsible for parsing these files, rendering the Markdown to HTML, and injecting the content into an HTML email template.

A typical newsletter frontmatter looks like this:

---
subject: Weekly Newsletter - {{date}}
date: {{current_date}}
status: draft
scheduled_at: 
website_url: https://example.com
github_url: https://github.com/username
preferences_url: https://example.com/preferences
unsubscribe_url: https://example.com/unsubscribe
variables:
  author: Newsletter Team
  edition_number: 1
---

Sources: newsletters/newsletter-template.md, newsletter-program/src/core/newsletter-composer.js

Subscriber Management

Subscriber data is stored in an encrypted JSON file (subscribers.encrypted.json). The system uses an ENCRYPTION_KEY (a 32-byte key, Base64 encoded) stored as an environment variable to perform AES-256-CBC encryption on subscriber emails. This ensures that personal data is protected at rest. A suite of CLI commands is provided to manage subscribers, including adding, listing, updating, and exporting data in a GDPR-compliant manner.

Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md

Summary

The Home page of this portfolio is the front-facing entry to a sophisticated static site. It combines the Hexo static site generator with a highly customized matrix-flow theme that prioritizes both a unique aesthetic and strong frontend performance. The standout feature is the deeply integrated newsletter system, which showcases a creative and security-conscious architecture by using GitHub Issues and Actions as a serverless backend, complete with data encryption and automated workflows. This design choice effectively decouples the subscription mechanism from the static site itself, enhancing security and maintainability.

Home

Relevant source files

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

Site Architecture

The portfolio is a static site generated by Hexo. The core configuration is managed in the root _config.yml file, which defines site metadata, URL structure, and the theme.

Framework: Hexo
Theme: matrix-flow
Deployment: Git-based deployment to GitHub Pages.

Sources: _config.yml:83, _config.yml:87-94

Build Process

The diagram below illustrates the high-level build and deployment flow.

Generating architecture diagram...

This diagram shows how Hexo combines source files and the theme to produce static assets, which are then deployed.
Sources: _config.yml:18, src/t.txt

Frontend & Layout

The visual presentation is defined by the matrix-flow theme, which implements a "Matrix"-inspired design.

Visual Style

The theme uses a dark background, green text, and a monospace font to create a terminal-like feel. Key visual elements include:

A fixed canvas (#matrix-canvas) for a falling characters background effect.
A scan-line overlay animation to mimic an old CRT monitor.
A "glitch" text effect on the main logo.

These styles are defined in the main stylesheet.

Sources: themes/matrix-flow/source/css/style.css:5-23, themes/matrix-flow/source/css/style.css:91-155

Layout System

The theme employs a responsive, full-screen layout using CSS Grid. The main layout containers are:

.fullscreen-container: A flex container that fills the viewport.
.responsive-grid: A CSS Grid that organizes the header, main content, sidebar, and footer.

The grid layout adapts to different screen sizes using media queries, ensuring a consistent experience on desktop, tablet, and mobile devices.

Sources: themes/matrix-flow/source/css/style.css:61-89, themes/matrix-flow/tests/fullscreen-layout-performance.test.js:100-106

Performance Optimization: Critical CSS

The CriticalCSSExtractor class identifies critical rules based on a predefined list of selectors, such as html, body, .fullscreen-container, and .logo-glitch.

The extraction process is as follows:

Generating architecture diagram...

This diagram shows the process of separating and inlining critical CSS for faster page loads.
Sources: themes/matrix-flow/scripts/critical-css-extractor.js, themes/matrix-flow/scripts/critical-css.js

Newsletter System

Configuration

The newsletter feature is enabled and configured in both the main _config.yml and the theme's themes/matrix-flow/_config.yml.

Parameter	Description	Source File
`enabled`	Toggles the newsletter feature on or off.	`_config.yml:71`
`discord_webhook`	URL for sending notifications to Discord.	`_config.yml:72`
`github_owner`	The GitHub username or organization that owns the repository.	`themes/matrix-flow/_config.yml:14`
`github_repo`	The name of the repository where subscription issues will be created.	`themes/matrix-flow/_config.yml:15`
`use_github_redirect`	If `true`, redirects the user to GitHub to create the issue.	`themes/matrix-flow/_config.yml:18`
`position`	Determines where the newsletter widget is displayed (`sidebar`, `footer`).	`themes/matrix-flow/_config.yml:24`

Subscription Flow

The end-to-end subscription process is entirely automated, starting from the user's interaction with the form on the website.

The following sequence diagram illustrates the complete flow from form submission to receiving a welcome email.

Generating architecture diagram...

Frontend Subscription (`newsletter.js`)

The client-side logic is managed by the NewsletterManager class in themes/matrix-flow/source/js/newsletter.js. Its primary responsibilities are:

Event Handling: Listens for form submission and input changes.
Real-time Validation:
- Validates the email format using a regex.
- Checks for common domain typos (e.g., gamil.com instead of gmail.com).
- Blocks disposable email addresses.
- Ensures the consent checkbox is ticked.
State Management: Manages form state, including submission status and validation errors, and disables the submit button accordingly.
GitHub Issue Generation: On successful validation, it constructs a URL to create a new GitHub issue. The user is redirected to this URL to complete the submission. The issue body is pre-filled with the form data in a structured format.

The handleSubmit function orchestrates this process.

// A simplified view of the form data collection and issue body generation
collectFormData() {
    const email = document.getElementById('newsletter-email').value.trim();
    const frequency = document.getElementById('newsletter-frequency').value;
    const topics = Array.from(document.querySelectorAll('input[name="topics"]:checked')).map(cb => cb.value);
    
    return { email, frequency, topics, /* ... */ };
}

generateIssueBody(formData) {
    // ...
    return `### Email Address\n\n${formData.email}\n\n### Newsletter Frequency\n\n${formData.frequency}\n\n...`;
}

Sources: themes/matrix-flow/source/js/newsletter.js:123-189, themes/matrix-flow/source/js/newsletter.js:253-311, themes/matrix-flow/source/js/newsletter.js:380-413

Backend Processing and Content

The newsletter-program directory contains the tools for managing newsletters and subscribers.

Newsletter Composition

A typical newsletter frontmatter looks like this:

---
subject: Weekly Newsletter - {{date}}
date: {{current_date}}
status: draft
scheduled_at: 
website_url: https://example.com
github_url: https://github.com/username
preferences_url: https://example.com/preferences
unsubscribe_url: https://example.com/unsubscribe
variables:
  author: Newsletter Team
  edition_number: 1
---

Sources: newsletters/newsletter-template.md, newsletter-program/src/core/newsletter-composer.js

Subscriber Management

Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md

Home

Site Architecture

Build Process

Frontend & Layout

Visual Style

Layout System

Performance Optimization: Critical CSS

Newsletter System

Configuration

Subscription Flow

Frontend Subscription (newsletter.js)

Backend Processing and Content

Newsletter Composition

Subscriber Management

Summary

Home

Site Architecture

Build Process

Frontend & Layout

Visual Style

Layout System

Performance Optimization: Critical CSS

Newsletter System

Configuration

Subscription Flow

Frontend Subscription (newsletter.js)

Backend Processing and Content

Newsletter Composition

Subscriber Management

Summary

Frontend Subscription (`newsletter.js`)

Frontend Subscription (`newsletter.js`)