# Hallmark Backend Architecture Explained: How a Static‑First Skill Runs Without a Server > Discover Hallmark's unique static-first backend architecture where all logic runs client-side. Learn how this innovative approach eliminates traditional server needs for efficient skill execution. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: architecture - Published: 2026-08-03 --- **Hallmark has no traditional backend—it is a static‑site‑only architecture where all logic runs client‑side, with only a lightweight Python HTTP server for local development.** The Hallmark repository by Nutlope demonstrates a backend‑less approach to building AI‑assisted design tools. Rather than deploying servers, databases, or APIs, Hallmark ships as a collection of static HTML, CSS, and JavaScript files that AI coding assistants consume directly. This article breaks down every component of this architecture using the actual source files. ## What "Backend Architecture" Means for Hallmark In conventional web applications, the backend architecture includes application servers, databases, and API layers. Hallmark inverts this model entirely. According to the Nutlope/hallmark source code, the architecture consists of three distinct parts that all operate without server‑side execution: - **Static assets** pre‑generated for direct browser rendering - **Skill metadata** that informs AI agents how to invoke Hallmark - **Local development server** used only for previewing, not production ## Component 1: Static Assets as the Foundation All user‑facing content lives in the `site/` directory as ordinary web files. The browser loads and executes these directly without any intermediate processing. | Asset Type | Location | Purpose | |------------|----------|---------| | HTML entry point | [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) | Main landing page with theme configuration | | Stylesheets | `site/css/*` | Design tokens and component styles | | JavaScript | [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) | Client‑side interactivity | | Examples | `site/examples/*/index.html` | Generated design showcases | The [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) file exemplifies this static approach: ```html ``` There is no templating engine, no server‑side rendering, and no dynamic route handling. The `data-theme="hum"` attribute on the `` element is read by client‑side JavaScript in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) to switch themes locally. ## Component 2: Skill Metadata in package.json Hallmark's integration with AI coding assistants depends entirely on declarative metadata. The [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) file contains a `"skill"` section that specifies how agents should load and execute Hallmark: ```json { "name": "hallmark", "version": "1.1.0", "type": "module", "files": ["skills"], "skill": { "entry": "skills/hallmark/SKILL.md", "references": "skills/hallmark/references", "harnesses": ["claude-code", "cursor", "codex"] } } ``` This metadata serves three functions: - **`entry`**: Points to [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), the Markdown file containing design rules and prompt templates - **`references`**: Indicates the directory with additional reference materials for the AI - **`harnesses`**: Declares which AI tools can invoke this skill (Claude Code, Cursor, and Codex) No runtime code executes when an AI assistant "runs" Hallmark. The assistant reads the Markdown skill definition, applies the design rules, and generates new static files that follow Hallmark's conventions. ## Component 3: Local Development Server The only server‑like component is a development convenience, not a production requirement. As defined in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json): ```json { "scripts": { "serve": "python3 -m http.server --directory site 4173" } } ``` Running `npm run serve` executes Python's built‑in HTTP server to serve the `site/` directory on port 4173. This server: - Has zero custom logic—it only serves static files - Is not used in production deployments - Can be replaced by any static hosting service (Vercel, Netlify, GitHub Pages) ## Client‑Side Logic Implementation All application behavior runs in the browser. The [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) file handles interactions like theme selection without server communication: ```javascript document.addEventListener('DOMContentLoaded', () => { const themeTrigger = document.querySelector('[data-theme-trigger]'); themeTrigger.addEventListener('click', () => { // UI logic only; no server calls // Toggles data-theme attribute and updates CSS custom properties }); }); ``` Similarly, example pages under `site/examples/` contain self‑contained scripts. For instance, [`site/examples/riso-01/script.js`](https://github.com/Nutlope/hallmark/blob/main/site/examples/riso-01/script.js) powers presentation slides entirely through DOM manipulation. ## How AI Assistants Use This Architecture When an AI coding assistant invokes Hallmark, the process follows this static‑first flow: 1. **Read**: The agent loads [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and parses the design system rules 2. **Apply**: Using the rules, the agent generates new HTML, CSS, and JavaScript files 3. **Output**: The generated files are written to a location where they can be served statically The "backend" of this process is the AI assistant's own infrastructure—not Hallmark's. Hallmark merely provides the specification and reference implementations. ## Key Architectural Characteristics - **Zero server dependencies**: No Node.js runtime, no database, no API gateway required for production - **CDN‑deployable**: Static files can be cached and distributed globally without application‑layer configuration - **Version‑controlled design**: The [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) file and `references/` directory capture the design system in plain text, enabling git‑based versioning and collaboration - **Harness portability**: The same skill definition works across multiple AI tools without code changes ## File Reference Summary | File | Role in Architecture | |------|----------------------| | [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) | Declares skill metadata and development scripts | | [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | AI‑readable specification for design rule application | | [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) | Static entry point for browser rendering | | [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) | Centralized design tokens (colors, spacing, typography) | | [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) | Client‑side theme switching and UI logic | | `site/examples/*/index.html` | Self‑contained generated design demonstrations | ## Summary - Hallmark operates as a **static‑only architecture** with no production backend services - The [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) **skill metadata** enables AI assistant integration without runtime code - A **Python HTTP server** (`python3 -m http.server`) provides local previewing only - All logic executes **client‑side** in JavaScript loaded by static HTML files - AI assistants consume the Markdown skill definition to **generate new static files**, not to execute server functions ## Frequently Asked Questions ### Does Hallmark require a backend server for production? No. Hallmark ships as static HTML, CSS, and JavaScript files that can be deployed to any static hosting service. The `npm run serve` command launches a Python HTTP server solely for local development and testing. ### How do AI coding assistants "run" Hallmark without a backend API? AI assistants read the declarative skill definition in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and apply the embedded design rules to generate new files. There is no API call—just file reading and content generation based on the specification. ### What is the purpose of the "harnesses" field in package.json? The `harnesses` array declares which AI tools can invoke Hallmark: `claude-code`, `cursor`, and `codex`. This metadata allows compatible agents to discover and load the skill automatically. ### Can Hallmark handle dynamic data or user authentication? Not in its current form. Hallmark is designed for static design system application. Dynamic functionality would require extending the architecture with external services or client‑side integration with serverless APIs.