# 0trebor0/buildhtml architecture

> Architecture diagram of the GitHub repository 0trebor0/buildhtml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0trebor0/buildhtml
- Repository: https://github.com/0trebor0/buildhtml

## Overview

@trebor/buildhtml is a Node.js library that turns server-authored pages into complete HTML, with browser JavaScript generated only when reactive features are used. The principal workflow is application code → page/document and element construction → rendering and optional client-code compilation → HTML response. Additional capabilities include reusable components, JSON construction, templates, SPA routing, CSS compilation, streaming, middleware caching, and metrics. Source excerpts support the core construction and rendering relationships; several secondary capabilities are documented or indexed but not fully sampled.

Main entry points: [`lib/document.js`](https://github.com/0trebor0/buildhtml/blob/main/lib/document.js) (Page document), [`lib/index.js`](https://github.com/0trebor0/buildhtml/blob/main/lib/index.js) (Public API), [`lib/renderer.js`](https://github.com/0trebor0/buildhtml/blob/main/lib/renderer.js) (HTML and client renderer), [`lib/element.js`](https://github.com/0trebor0/buildhtml/blob/main/lib/element.js) (Element tree)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Page authoring"]
  node_api["Public API<br/>[index.js]"]
  node_document["Page document<br/>[document.js]"]
  node_element["Element tree<br/>[element.js]"]
  node_components["Components<br/>[components.js]"]
  node_builder["JSON builder<br/>[builder.js]"]
  node_templates["Templates<br/>[template.js]"]
end

subgraph group_rendering["Rendering and reactivity"]
  node_spa["SPA features<br/>[live.js]"]
  node_renderer["HTML and client renderer<br/>[renderer.js]"]
  node_css["CSS compiler<br/>[css.js]"]
  node_head["Document head<br/>[head.js]"]
end

subgraph group_delivery["Delivery and operations"]
  node_middleware["HTTP middleware<br/>[middleware.js]"]
  node_cache[("Render cache<br/>[cache.js]")]
  node_metrics["Metrics<br/>[metrics.js]"]
  node_pools["Object pools<br/>[pools.js]"]
end

subgraph group_foundation["Shared foundations"]
  node_config["Configuration<br/>[config.js]"]
  node_utils["Safety utilities<br/>[utils.js]"]
end

node_app(("Node application"))
node_response["HTML response"]

node_app -->|"uses"| node_api
node_api -->|"creates pages"| node_document
node_api -->|"builds JSON"| node_builder
node_api -->|"exposes templates"| node_templates
node_api -->|"exposes middleware"| node_middleware
node_api -->|"exposes SPA tools"| node_spa
node_document -->|"creates elements"| node_element
node_document -->|"applies components"| node_components
node_element -->|"applies components"| node_components
node_builder -->|"applies components"| node_components
node_builder -->|"compiles lists"| node_spa
node_document -->|"builds head"| node_head
node_document -->|"renders page"| node_renderer
node_renderer -->|"embeds client CSS"| node_css
node_element -->|"compiles styles"| node_css
node_element -->|"sanitizes values"| node_utils
node_renderer -->|"escapes output"| node_utils
node_document -->|"reads cache"| node_cache
node_middleware -->|"renders documents"| node_document
node_middleware -->|"records metrics"| node_metrics
node_document -->|"recycles objects"| node_pools
node_pools -->|"counts reuse"| node_metrics
node_cache -->|"records cache stats"| node_metrics
node_document -->|"reads settings"| node_config
node_renderer -->|"reads settings"| node_config
node_css -->|"reads settings"| node_config
node_renderer -->|"produces HTML"| node_response

click node_api "https://github.com/0trebor0/buildhtml/blob/main/lib/index.js"
click node_document "https://github.com/0trebor0/buildhtml/blob/main/lib/document.js"
click node_element "https://github.com/0trebor0/buildhtml/blob/main/lib/element.js"
click node_components "https://github.com/0trebor0/buildhtml/blob/main/lib/components.js"
click node_builder "https://github.com/0trebor0/buildhtml/blob/main/lib/builder.js"
click node_templates "https://github.com/0trebor0/buildhtml/blob/main/lib/template.js"
click node_spa "https://github.com/0trebor0/buildhtml/blob/main/lib/live.js"
click node_renderer "https://github.com/0trebor0/buildhtml/blob/main/lib/renderer.js"
click node_css "https://github.com/0trebor0/buildhtml/blob/main/lib/css.js"
click node_head "https://github.com/0trebor0/buildhtml/blob/main/lib/head.js"
click node_middleware "https://github.com/0trebor0/buildhtml/blob/main/lib/middleware.js"
click node_cache "https://github.com/0trebor0/buildhtml/blob/main/lib/cache.js"
click node_metrics "https://github.com/0trebor0/buildhtml/blob/main/lib/metrics.js"
click node_pools "https://github.com/0trebor0/buildhtml/blob/main/lib/pools.js"
click node_config "https://github.com/0trebor0/buildhtml/blob/main/lib/config.js"
click node_utils "https://github.com/0trebor0/buildhtml/blob/main/lib/utils.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_document,node_element,node_components,node_builder,node_templates toneBlue
class node_spa,node_renderer,node_css,node_head toneAmber
class node_middleware,node_cache,node_metrics,node_pools toneMint
class node_config,node_utils toneRose
class node_app,node_response toneIndigo
```

## Components

### Page authoring

- [Public API](https://github.com/0trebor0/buildhtml/blob/main/lib/index.js): `lib/index.js`
- [Page document](https://github.com/0trebor0/buildhtml/blob/main/lib/document.js): `lib/document.js`
- [Element tree](https://github.com/0trebor0/buildhtml/blob/main/lib/element.js): `lib/element.js`
- [Components](https://github.com/0trebor0/buildhtml/blob/main/lib/components.js): `lib/components.js`
- [JSON builder](https://github.com/0trebor0/buildhtml/blob/main/lib/builder.js): `lib/builder.js`
- [Templates](https://github.com/0trebor0/buildhtml/blob/main/lib/template.js): `lib/template.js`

### Rendering and reactivity

- [SPA features](https://github.com/0trebor0/buildhtml/blob/main/lib/live.js): `lib/live.js`
- [HTML and client renderer](https://github.com/0trebor0/buildhtml/blob/main/lib/renderer.js): `lib/renderer.js`
- [CSS compiler](https://github.com/0trebor0/buildhtml/blob/main/lib/css.js): `lib/css.js`
- [Document head](https://github.com/0trebor0/buildhtml/blob/main/lib/head.js): `lib/head.js`

### Delivery and operations

- [HTTP middleware](https://github.com/0trebor0/buildhtml/blob/main/lib/middleware.js): `lib/middleware.js`
- [Render cache](https://github.com/0trebor0/buildhtml/blob/main/lib/cache.js): `lib/cache.js`
- [Metrics](https://github.com/0trebor0/buildhtml/blob/main/lib/metrics.js): `lib/metrics.js`
- [Object pools](https://github.com/0trebor0/buildhtml/blob/main/lib/pools.js): `lib/pools.js`

### Shared foundations

- [Configuration](https://github.com/0trebor0/buildhtml/blob/main/lib/config.js): `lib/config.js`
- [Safety utilities](https://github.com/0trebor0/buildhtml/blob/main/lib/utils.js): `lib/utils.js`

### Other components

- **Node application**
- **HTML response**

## Connections

- Node application → Public API: uses (evidence: `README.md`)
- Public API → Page document: creates pages (evidence: `lib/index.js`)
- Public API → JSON builder: builds JSON (evidence: `lib/index.js`)
- Public API → Templates: exposes templates (evidence: `lib/index.js`)
- Public API → HTTP middleware: exposes middleware (evidence: `lib/index.js`)
- Public API → SPA features: exposes SPA tools (evidence: `lib/index.js`)
- Page document → Element tree: creates elements (evidence: `lib/document.js`)
- Page document → Components: applies components (evidence: `lib/document.js`)
- Element tree → Components: applies components (evidence: `lib/element.js`)
- JSON builder → Components: applies components (evidence: `lib/builder.js`)
- JSON builder → SPA features: compiles lists (evidence: `lib/builder.js`)
- Page document → Document head: builds head (evidence: `lib/document.js`)
- Page document → HTML and client renderer: renders page (evidence: `lib/document.js`)
- HTML and client renderer → CSS compiler: embeds client CSS (evidence: `lib/renderer.js`)
- Element tree → CSS compiler: compiles styles (evidence: `lib/element.js`)
- Element tree → Safety utilities: sanitizes values (evidence: `lib/element.js`)
- HTML and client renderer → Safety utilities: escapes output (evidence: `lib/renderer.js`)
- Page document → Render cache: reads cache (evidence: `lib/document.js`)
- HTTP middleware → Page document: renders documents (evidence: `lib/middleware.js`)
- HTTP middleware → Metrics: records metrics (evidence: `lib/middleware.js`)
- Page document → Object pools: recycles objects (evidence: `lib/document.js`)
- Object pools → Metrics: counts reuse (evidence: `lib/pools.js`)
- Render cache → Metrics: records cache stats (evidence: `lib/cache.js`)
- Page document → Configuration: reads settings (evidence: `lib/document.js`)
- HTML and client renderer → Configuration: reads settings (evidence: `lib/renderer.js`)
- CSS compiler → Configuration: reads settings (evidence: `lib/css.js`)
- HTML and client renderer → HTML response: produces HTML (evidence: `README.md`)
