How Archify's Self-Contained HTML Output Achieves Zero Runtime Dependencies

Archify generates HTML files that embed all CSS, JavaScript, SVG data, and font definitions directly into a single document, allowing diagrams to render completely offline without external libraries, stylesheets, or network requests.

The tt-a1i/archify repository provides a CLI tool that converts JSON architecture descriptions into interactive visual diagrams. Unlike web-based diagramming tools that require persistent internet access or external CDN dependencies, archify's self-contained HTML output packages every resource needed for rendering into one portable file. This architectural decision ensures that generated diagrams function in air-gapped environments, can be attached to emails, and remain readable years after creation without suffering from link rot or deprecated dependencies.

Inlined CSS and Theme Variables

Archify eliminates external stylesheet dependencies by embedding the entire CSS payload directly inside the HTML template. In archify/assets/template.html (lines 36-88), a comprehensive <style> block contains all rules for the diagram layout, toolbar components, card styling, and print-specific formatting.

The theming system relies on CSS custom properties rather than external theme files. Variables such as --bg, --grid, and --text are defined within [data-theme="dark"] and [data-theme="light"] selectors, enabling instant theme switching without network requests. Because these properties live inside the inlined stylesheet, the browser can apply color schemes immediately upon parsing the document.

Standalone JavaScript Implementation

All interactive functionality is implemented through a minimal, zero-dependency JavaScript module embedded directly in the template. The Archify.theme utility (located at lines 40-85 of archify/assets/template.html) handles theme detection and persistence through a cascading fallback strategy:

1. Checks the theme URL parameter
2. Falls back to localStorage if no parameter exists
3. Defaults to the OS-level color scheme preference
4. Persists user selection back to localStorage
5. Listens for system-level theme changes via matchMedia events

This self-contained approach requires no external JavaScript libraries such as jQuery, React, or Vue. The entire runtime logic fits within a single <script> tag that executes immediately when the browser parses the HTML.

Self-Serializing SVG Export Pipeline

Archify's export functionality operates entirely within the browser using native APIs, requiring no external services or server-side processing. The raster export feature (implemented around lines 3340-3420 of archify/assets/template.html) serializes the SVG at scale = 4 to generate high-DPI PNG, JPEG, or WebP images using the HTML5 Canvas API.

For vector exports, Archify generates a dual-theme SVG that embeds both dark and light CSS variables alongside a prefers-color-scheme media query. This ensures that exported SVG files automatically adapt to the viewer's system preferences even when opened as standalone files. The rasterization process occurs entirely client-side, leveraging canvas.toDataURL() without contacting external image processing services.

Embedded Font Handling with Local Fallbacks

While the generated HTML includes a <link> reference to Google Fonts for optimal initial loading, the exported SVG files contain embedded @font-face declarations that reference system fonts. Specifically, the template includes a fallback rule referencing local('JetBrains Mono') (lines 14-35 of archify/assets/template.html), ensuring that text renders correctly using locally installed fonts when the external Google Fonts CDN is unavailable.

This dual-strategy approach optimizes for network-connected viewing while guaranteeing that the standalone HTML file remains functional offline. The font declarations are embedded directly in the document's <style> block, eliminating the need for separate font files or external CSS requests.

Encapsulated SVG Architecture

Diagram elements use semantic CSS classes (such as .c-frontend, .c-backend, and .a-default) rather than inline fill or stroke attributes. This separation of concerns means that the SVG markup injected into the template remains clean and the styling inherits from the embedded CSS stylesheet.

The rendering pipeline in archify/renderers/architecture/render-architecture.mjs and archify/renderers/workflow/render-workflow.mjs generates SVG markup that references these classes. When combined with the inlined CSS in the final output, this approach ensures that every visual aspect of the diagram is self-contained within the single HTML file. The CLI entry point at archify/bin/archify.mjs orchestrates this process by reading JSON input, invoking the appropriate renderer, and injecting the resulting markup into the template slots designated by <!-- ARCHIFY:SVG_SLOT_START --> and <!-- ARCHIFY:SVG_SLOT_END -->.

Summary

• Inlined Resources: All CSS, JavaScript, and font definitions are embedded directly in archify/assets/template.html, eliminating external HTTP requests.
• Native APIs: Theme detection, localStorage persistence, and image export rely solely on browser-native JavaScript and Canvas APIs.
• Dual-Theme SVGs: Exported vectors embed both color schemes with media queries, ensuring compatibility without external stylesheets.
• Local Font Fallbacks: The template includes @font-face rules with local font references to maintain typography offline.
• Semantic Styling: SVG elements use CSS classes rather than inline styles, inheriting visual properties from the embedded stylesheet.

Frequently Asked Questions

Can Archify HTML files work completely offline?

Yes. Once generated, an Archify HTML file contains every resource required for rendering, including all CSS rules, JavaScript logic, SVG markup, and font fallbacks. You can open the file in any modern browser without an internet connection, and all features including theme toggling, zoom controls, and export functionality will operate normally.

How does theme switching work without external CSS files?

The theme system uses CSS custom properties defined in an inlined <style> block. When you toggle themes or the system detects a preference change, JavaScript updates the data-theme attribute on the <html> element. The browser immediately recalculates styles using the embedded CSS variables—no external stylesheets are fetched or required.

Are exported SVGs also self-contained?

Yes. When exporting to SVG format, Archify creates a standalone file that embeds both dark and light theme CSS variables along with prefers-color-scheme media queries. These exported SVGs include @font-face declarations with local font references, ensuring they display correctly regardless of network connectivity or external resource availability.

What browser versions support these self-contained files?

Archify's HTML output targets modern evergreen browsers that support CSS custom properties, the Canvas API, and ES6 JavaScript features. This includes Chrome 60+, Firefox 55+, Safari 12+, and Edge 79+. The files do not require specific framework runtimes or polyfills, making them highly compatible across platforms.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}