Codex Design Architecture

Relevant source files

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

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

The Codex Design is an alternate, self-contained interface for exploring the Norm Macdonald joke archive. It is implemented using vanilla HTML, CSS, and JavaScript, requiring no build tools, which allows it to be served statically. This approach contrasts with other versions in the repository, such as the redesign prototype and the older React-based application found in old/site-src.

This architecture prioritizes simplicity and direct DOM manipulation. Its key features include a "Spotlight" section for random jokes, combined search and filter functionality, and a persistent light/dark theme toggle. The entire experience is delivered through three core files: index.html for structure, styles.css for presentation, and script.js for all interactive logic.

Sources: README.md:31-47, codex-design/index.html, codex-design/script.js, codex-design/styles.css, old/site-src/App.jsx

System Components

The application's UI is divided into four primary structural components defined in the HTML.

Component	HTML Element/Class	Description	Source File
App Header	<header class="app-header">	Contains the branding, title, and the theme toggle button.	codex-design/index.html:8-17
Spotlight	<section class="highlight">	Features a single, randomly selected joke. Includes a "Shuffle Spotlight" button to load a new one.	codex-design/index.html:19-29
Filters	<section class="filters">	Provides user controls for refining the joke list, including a text search and dropdowns for guest/source.	codex-design/index.html:31-47
Results	<section class="results">	Displays the list of joke cards that match the current filter criteria and shows a count of results.	codex-design/index.html:49-54

This diagram illustrates the high-level component structure of the page.

Styling and Theming

The visual presentation is managed by codex-design/styles.css and features a robust theming system built on CSS Custom Properties.

Theme Architecture

The system supports both light and dark themes, respects the user's operating system preference (prefers-color-scheme), and persists the user's choice in localStorage.

• Theme Definition: Colors, fonts, and spacing are defined as CSS variables in the :root selector.
• Theme Switching: A data-theme attribute on the <html> element (<html lang="en" data-theme="light">) is used to toggle themes. The [data-theme="dark"] selector overrides the default light theme variables.
• Persistence: The initTheme function in script.js manages theme state, checking localStorage first, then prefers-color-scheme, and attaching a click event listener to the theme toggle button.

Sources: codex-design/styles.css:6-43, codex-design/script.js:10-33, codex-design/index.html:2

The following diagram shows the logic flow for initializing and changing the theme.

Core Functionality (JavaScript)

All interactivity is handled by codex-design/script.js, which operates as an ES6 module.

Application Initialization

On page load, the init() function orchestrates the entire setup process.

This sequence diagram shows the application's startup process.

Data Fetching and State

• Data Source: The application fetches joke data from ../jokes-data.json. This file is expected to be an array of joke objects.
• State Management: Application state, including the full list of jokes and filter values, is stored in module-level variables (jokes, filters). There is no complex state management library; state is managed directly within the script.

Sources: codex-design/script.js:4-8, 158

Filtering and Search Logic

The core of the application is the applyFilters function, which filters the master jokes array based on user input from the search field and dropdowns.

1. The function reads the current values from the search input and the guest and source select elements.
2. It filters the jokes array, applying each filter criterion sequentially. The search is case-insensitive.
3. After filtering, it calls renderResults to update the DOM with the matching jokes.
4. Event listeners on the filter controls (input for search, change for dropdowns) trigger applyFilters to provide a real-time experience.

This diagram illustrates the filtering process.

Rendering

• Joke Card Template: A <template id="joke-card"> element in index.html is used as a blueprint for creating joke cards. This is more efficient than building the HTML structure as a string in JavaScript.
• renderResults(): This function is responsible for displaying the filtered jokes. It clears the existing results, iterates over the filtered data, clones the template for each joke, populates it with data, and appends it to the results grid.
• populateSpotlight(): This function selects a random joke and populates the dedicated spotlight card, separate from the main results list.

Sources: codex-design/index.html:56-75, codex-design/script.js:85-119, 121-141

Conclusion

The Codex Design architecture is a lightweight, dependency-free solution for creating an interactive data exploration interface. By leveraging vanilla JavaScript (ES6), CSS Custom Properties, and semantic HTML with features like <template>, it achieves modern functionality without the overhead of frameworks or build steps. This makes it a simple, maintainable, and performant alternative to the React-based implementation seen elsewhere in the project.

Sources: README.md:44-47, old/site-src/App.jsx