Overall Architecture

Relevant source files

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

• README.md
• redesign/README.md
• old/site-src/App.jsx
• old/site-src/TODO.txt
• styles.css
• videos.js
• index.html
• codex-design/index.html

The norm repository contains the source code for "The Norm Macdonald Archive," a static fan-made tribute website. The architecture has evolved over time, resulting in several distinct implementations coexisting within the repository. The primary approach is a static site generated using vanilla HTML, CSS, and JavaScript, which consumes JSON data files for dynamic content. An older version exists as a React-based Single Page Application (SPA).

The project is structured into multiple directories, each representing a different version or a specific part of the site. The most current implementation appears to be the redesign version, which is a prototype built with pure HTML/CSS/JS, focusing on a modern aesthetic, theming, and enhanced user experience without the overhead of a framework.

Architectural Implementations

The repository hosts three main architectural patterns for the website, each with its own set of files and technology stack.

Version	Directory	Technology	Description
Redesign	/, /redesign/	Vanilla HTML/CSS/JS	A modern, framework-less prototype with multiple pages, theming, and client-side data fetching. This appears to be the primary, active version.
Old App	/old/site-src/	React	A single-page application built with React, using components to render different sections like Jokes, Videos, and Transcripts.
Codex Design	/codex-design/	Vanilla HTML/CSS/JS	An alternate, single-page interface for exploring the joke archive with a different UI/UX inspired by "Codex".

Sources: README.md:1-49, old/site-src/TODO.txt:4, codex-design/index.html:5-11

This diagram illustrates the high-level structure of the repository, showing the distinct application versions and the shared data sources.

Redesign Prototype Architecture

The redesign prototype is the most feature-complete vanilla JS implementation. It is a multi-page static site that uses client-side JavaScript to fetch and render content from JSON files.

Sources: redesign/README.md

Technology Stack

• HTML/CSS/JavaScript: No frameworks are used.
• CSS Custom Properties: Used for a light/dark theme system.
• ES6+ JavaScript: Modern JavaScript for interactivity.
• Responsive Design: Mobile-first approach.

Sources: redesign/README.md:29-33, styles.css:10-40

Structure and Data Flow

The application consists of several HTML pages (index.html, videos.html, transcripts.html, etc.) that share a common stylesheet (styles.css) and have their own dedicated JavaScript files for specific logic.

The general data flow for content pages like "Videos" is as follows:

1. The user navigates to a page (e.g., videos.html).
2. The corresponding JavaScript file (videos.js) is executed.
3. An async function (loadVideos) fetches the relevant JSON data (consolidated_youtube_data.json).
4. The fetched data is processed, normalized, and stored in a global state object.
5. JavaScript functions (renderVideos, renderPagination) dynamically create and inject HTML elements into the DOM to display the content.
6. User interactions like search or pagination trigger functions that filter the state object and re-render the view.

This flow is visualized in the diagram below.

Theming

The application supports both light and dark themes, which can be toggled by the user or set based on system preference. This is managed using CSS Custom Properties (variables) defined in :root. A data-theme attribute on the <html> element switches between color palettes.

Theme Variables Example:

/* styles.css:10-40 */
:root {
    /* Modern Dark Color Palette - Stitch Inspired */
    --studio-dark: #0D1117;
    --studio-surface: #161B22;
    --text-primary: #E6EDF3;
    --accent-blue: #3882F6;

    /* Light Theme */
    --light-bg: #FFFFFF;
    --light-surface: #F6F8FA;
    --light-text-primary: #1F2328;

    /* Default to dark */
    --bg-primary: var(--studio-dark);
    --text-1: var(--text-primary);
    --accent: var(--accent-blue);
}

/* Light Theme */
:root[data-theme="light"] {
    --bg-primary: var(--light-bg);
    --bg-secondary: var(--light-surface);
    --text-1: var(--light-text-primary);
}

A JavaScript function initTheme handles checking localStorage and prefers-color-scheme to apply the correct theme on load and manages the theme toggle button.

Sources: styles.css:10-104, index.html:206-231

Old React App Architecture

Located in old/site-src/, this version is a Single Page Application (SPA) built with React.

Sources: old/site-src/TODO.txt:4

Structure

The application's entry point is old/index.html, which mounts the React application into the <div id="root">. The main application logic resides in old/site-src/App.jsx.

This component diagram shows the structure of the App.jsx component.

State Management and Navigation

The App component uses the useState hook to manage the currently visible section (activeSection). Navigation is handled by the handleNavigation function, which updates this state variable, causing React to conditionally render the corresponding section component (JokesSection, VideosSection, etc.). This simulates page navigation within a single-page application.

Sources: old/site-src/App.jsx:27, 67-72, 273-281

Build and Deployment

The old/site-src/TODO.txt file outlines the build and deployment process for the React application:

1. Run pnpm run build to create a production build.
2. Copy the consolidated_youtube_data.json file into the dist folder.
3. The generated static assets in the dist folder are then copied to the site/ directory at the root of the repository for serving.

Sources: old/site-src/TODO.txt:10-12, README.md:40-42

Data Sources

The site's content is primarily driven by two JSON files.

Filename	Purpose	Example Fields
jokes-data.json	Contains a database of 76 jokes.	joke, guest, episode, timestamp, video_id
consolidated_youtube_data.json	Contains metadata for 939 YouTube videos.	Video url, Title, Description, Channel name, Views

Sources: redesign/README.md:25, videos.html:62, videos.js:50-58

The JavaScript in both the redesign and old applications fetches these files to populate the UI, allowing content updates without changing the core HTML or application code.

Conclusion

The norm repository showcases an architectural evolution from a framework-based SPA (React) to a lighter, more direct static site architecture using vanilla JavaScript. The current redesign emphasizes performance, simplicity, and maintainability by avoiding framework dependencies and relying on standard web technologies. All versions are designed to be served statically, consuming structured JSON files to render dynamic content, which separates the data from the presentation layer effectively.