System Architecture Overview

Relevant source files

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

• _config.yml
• newsletter-program/README-SUBSCRIBER-MANAGEMENT.md
• newsletter-program/src/core/newsletter-composer.js
• newsletter-program/src/tests/integration/newsletter-subscription-flow.test.js
• newsletters/README.md
• newsletters/newsletter-template.md
• src/t.txt
• themes/matrix-flow/CSS-INTEGRATION-README.md
• themes/matrix-flow/README-newsletter.md
• themes/matrix-flow/_config.yml
• themes/matrix-flow/scripts/critical-css-extractor.js
• themes/matrix-flow/source/js/newsletter.js
• themes/matrix-flow/tests/fullscreen-layout-performance.test.js

This document provides a technical overview of the system architecture for the portfolio project. The system is a composite architecture, combining a Hexo-based static website with a custom, performance-oriented theme (matrix-flow), and a decoupled Node.js-based newsletter management system. The architecture prioritizes performance, automation, and security, particularly for the newsletter and subscriber data.

The diagram below illustrates the high-level components and their interactions.

Core Technology Stack

The project is built upon three main pillars:

1. Hexo Static Site: The core of the portfolio website is generated by the Hexo framework. It processes markdown source files into a static dist directory.
2. matrix-flow Theme: A custom, highly-optimized theme that provides the site's layout, styling, and frontend functionality. It includes advanced performance features like critical CSS extraction.
3. Newsletter Program: A standalone Node.js application for composing, managing, and sending newsletters, with a secure, encrypted, file-based subscriber management system.

Sources: _config.yml:84, themes/matrix-flow/CSS-INTEGRATION-README.md, newsletter-program/README-SUBSCRIBER-MANAGEMENT.md

Static Site Generation

The website is generated using Hexo. The main configuration is located in _config.yml. The build process reads content from the source/ directory, applies the matrix-flow theme, and outputs the final static files to the public_dir (configured as ./dist).

Sources: _config.yml:19-20

Build Process

The build process, triggered by npx hexo generate, performs the following steps:

1. Cleans the public and db directories.
2. Loads all source files (Markdown posts, assets, etc.).
3. Renders Markdown content into HTML pages.
4. Processes theme assets, including running theme-specific scripts for CSS optimization.
5. Generates final HTML, CSS, JS, and other asset files into the ./dist directory.

The following diagram shows the Hexo generation flow.

Deployment

Deployment is handled via a Git-based strategy, pushing the contents of the dist folder to a specified GitHub repository. This is configured in the deploy section of _config.yml.

# _config.yml:88-96
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:88-96

matrix-flow Theme Architecture

The matrix-flow theme is responsible for the site's appearance and frontend performance. It features a responsive, fullscreen grid layout and a sophisticated CSS optimization strategy.

Sources: themes/matrix-flow/tests/fullscreen-layout-performance.test.js:101-108, themes/matrix-flow/CSS-INTEGRATION-README.md

CSS Optimization

To improve rendering performance and avoid Flash of Unstyled Content (FOUC), the theme employs a Critical CSS strategy. Instead of using preload, it extracts "above-the-fold" styles and inlines them directly into the HTML <head>.

The process is managed by themes/matrix-flow/scripts/critical-css-extractor.js.

1. Identify Critical Selectors: A predefined list of selectors essential for the initial viewport is maintained.
2. Extract Rules: The script reads the main stylesheet and filters out CSS rules matching the critical selectors.
3. Optimize & Minify: The extracted critical CSS is minified.
4. Generate Partials: Two files are generated:
   • layout/_partial/critical-css.ejs: An EJS partial containing the inlined critical CSS within <style> tags.
   • scripts/css-helpers.js: Hexo helpers to load the non-critical CSS asynchronously.

This diagram shows the splitting of CSS into critical (inlined) and non-critical (async loaded) parts.
Sources: themes/matrix-flow/scripts/critical-css-extractor.js, themes/matrix-flow/CSS-INTEGRATION-README.md

Critical Selectors

The CriticalCSSExtractor class defines selectors that are considered critical for the initial page render.

// themes/matrix-flow/scripts/critical-css-extractor.js:19-43
this.criticalSelectors = [
    // Layout structure
    'html', 'body', '*',
    '.fullscreen-container',
    '.responsive-grid',
    '.site-header',
    '.site-main',
    '.main-content',
    
    // Critical visual elements
    '.logo-glitch',
    '.main-nav',
    '.nav-item',
    '#matrix-canvas',
    
    // Above-the-fold content
    '.post-list-item:first-child',
    '.post-title',
    '.post-meta',
    
    // Essential animations and transitions
    '@keyframes scan',
    '@keyframes glitch-anim-1',
    '@keyframes glitch-anim-2',
    
    // Critical responsive breakpoints
    '@media (max-width: 768px)',
    '@media (max-width: 480px)'
];

Sources: themes/matrix-flow/scripts/critical-css-extractor.js:19-43

Newsletter System

The newsletter system is a standalone Node.js application that integrates with the main site. It handles everything from subscriber acquisition to newsletter composition and delivery.

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

Subscription Flow

The system uses GitHub Issues as a privacy-focused subscription mechanism.

1. A user fills out the newsletter form on the website.
2. The frontend JavaScript (newsletter.js) constructs a URL that pre-fills a new GitHub issue in the project repository.
3. The user is redirected to GitHub to create the issue, providing explicit action.
4. A GitHub Action is triggered by the creation of the issue.
5. The Action processes the issue, extracts subscriber data, encrypts the email, stores it, sends a welcome email via Resend, and posts a notification to Discord.
6. The issue is closed and scheduled for automatic deletion to protect user privacy.

The following sequence diagram illustrates this flow.

Newsletter Composition and Lifecycle

Newsletters are managed as Markdown files with YAML frontmatter within the /newsletters directory. A dedicated CLI facilitates their management.

Sources: newsletters/README.md:12-15

Newsletter File Format

---
subject: Newsletter Title
date: 2025-10-31
status: draft|scheduled|sent
scheduled_at: 2025-11-01T10:00:00Z
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
---

# Newsletter Content

Your markdown content here...

Sources: newsletters/README.md:17-30, newsletters/newsletter-template.md

Newsletter Lifecycle

The NewsletterComposer class and associated CLI scripts manage the lifecycle of a newsletter from creation to archival.

This diagram shows the state transitions of a newsletter file.
Sources: newsletters/README.md, newsletter-program/src/core/newsletter-composer.js

Subscriber Management

Subscriber data is managed securely in an encrypted file-based system, avoiding the need for an external database.

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

Data Model and Encryption

Subscriber information, particularly email addresses, is encrypted using AES-256-CBC. The encryption key is managed via environment variables. The data is stored in newsletter-program/src/data/subscribers.encrypted.json.

Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md:19-21, 107-111

The structure of a subscriber record is as follows:

Field	Type	Description
id	string	Unique subscriber identifier (UUID).
email	string	User's email, encrypted in storage.
status	string	active, unsubscribed, or bounced.
subscribedAt	string	ISO 8601 timestamp of subscription.
source	string	Origin of the subscription (e.g., website).
preferences	object	Contains frequency and topics.
unsubscribeToken	string	Secure token for one-click unsubscription.

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

Conclusion

The project's architecture is a well-structured blend of a static site generator and a separate, robust service for dynamic functionality (newsletters). Key architectural characteristics include:

• Decoupling: The portfolio site and the newsletter program are largely independent, communicating via GitHub Actions.
• Performance Focus: The matrix-flow theme heavily prioritizes fast rendering through techniques like critical CSS inlining.
• Automation: GitHub Actions are central to automating the newsletter subscription and sending processes.
• Security by Design: The newsletter system is built with privacy and security in mind, using strong encryption for subscriber data and a GitHub Issue-based flow that protects user credentials.

This modular design allows for independent development and maintenance of the content, theme, and newsletter system while providing a seamless experience on the frontend.