# sxijyoti/whiskey architecture

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

- Interactive diagram: https://gitdiagram.com/sxijyoti/whiskey
- Repository: https://github.com/sxijyoti/whiskey

## Overview

Whiskey is a dependency-aware static site generator. Its principal workflow builds a dependency graph, detects changed inputs, selects affected pages, synchronizes remote content into a workspace, and renders site output. The README documents that overall build sequence, but the central build implementation is not present in the supplied tree, so links among those stages cite the README rather than implying unseen calls. Live serving and remote HTML-to-Markdown extraction are also represented where the supplied excerpts show their behavior.

Main entry points: [`internal/cli/build.go`](https://github.com/sxijyoti/whiskey/blob/main/internal/cli/build.go) (CLI commands), [`internal/graph/builder.go`](https://github.com/sxijyoti/whiskey/blob/main/internal/graph/builder.go) (Dependency graph), [`internal/parser/markdown.go`](https://github.com/sxijyoti/whiskey/blob/main/internal/parser/markdown.go) (Markdown parser), [`internal/fingerprint/changed.go`](https://github.com/sxijyoti/whiskey/blob/main/internal/fingerprint/changed.go) (Input fingerprints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Build workflow"]
  node_config["Site configuration<br/>[config.go]"]
  node_graph["Dependency graph<br/>[builder.go]"]
  node_fingerprints[("Input fingerprints<br/>[changed.go]")]
  node_planner["Dirty-page planner<br/>[dirty.go]"]
end

subgraph group_sources["Source synchronization"]
  node_dependency_refs["Include resolution<br/>[resolve.go]"]
  node_source_registry["Source providers<br/>[registry.go]"]
  node_http_source["HTTP source fetch<br/>[http.go]"]
  node_materializer["Workspace materializer<br/>[materialize.go]"]
  node_workspace[("Persistent workspace<br/>[workspace.go]")]
  node_manifest[("Source cache manifest<br/>[manifest.go]")]
  node_extractor["HTML extraction<br/>[extract.go]"]
end

subgraph group_content["Content rendering"]
  node_parser["Markdown parser<br/>[markdown.go]"]
  node_frontmatter["Frontmatter metadata<br/>[frontmatter.go]"]
  node_shortcodes["Content shortcodes<br/>[shortcode.go]"]
  node_templates["Template renderer<br/>[render.go]"]
  node_template_engine["Template loading<br/>[engine.go]"]
end

subgraph group_experience["CLI and development"]
  node_cli["CLI commands<br/>[build.go]"]
  node_watcher["File watcher<br/>[watcher.go]"]
  node_devserver["Live-reload server<br/>[server.go]"]
end

node_user(("Site author"))
node_site_output["Generated site"]
node_browser(("Browser"))
node_remote_web(("Remote web"))

node_user -->|"runs commands"| node_cli
node_cli -.->|"loads settings"| node_config
node_cli -->|"inspects dependencies"| node_graph
node_graph -->|"parses metadata"| node_parser
node_graph -->|"resolves includes"| node_dependency_refs
node_graph -->|"resolves sources"| node_source_registry
node_fingerprints -->|"reads cached inputs"| node_workspace
node_graph -->|"tracks build inputs"| node_fingerprints
node_fingerprints -->|"reports changes"| node_planner
node_planner -->|"finds affected pages"| node_graph
node_planner -->|"selects rebuilds"| node_site_output
node_parser -.->|"extracts metadata"| node_frontmatter
node_parser -.->|"expands shortcodes"| node_shortcodes
node_templates -.->|"loads layouts"| node_template_engine
node_templates -->|"renders pages"| node_site_output
node_dependency_refs -.->|"resolves providers"| node_source_registry
node_source_registry -.->|"creates HTTP source"| node_http_source
node_http_source -->|"fetches content"| node_remote_web
node_http_source -->|"extracts HTML as Markdown"| node_extractor
node_extractor -->|"parses frontmatter"| node_parser
node_materializer -->|"stores sources"| node_workspace
node_materializer -.->|"tracks cache metadata"| node_manifest
node_workspace -->|"supplies render inputs"| node_templates
node_cli -->|"starts file watching"| node_watcher
node_cli -->|"starts live serving"| node_devserver
node_watcher -->|"triggers rebuilds"| node_cli
node_devserver -.->|"serves site and reloads"| node_browser
node_cli -->|"synchronizes sources"| node_materializer

click node_cli "https://github.com/sxijyoti/whiskey/blob/main/internal/cli/build.go"
click node_config "https://github.com/sxijyoti/whiskey/blob/main/internal/config/config.go"
click node_graph "https://github.com/sxijyoti/whiskey/blob/main/internal/graph/builder.go"
click node_fingerprints "https://github.com/sxijyoti/whiskey/blob/main/internal/fingerprint/changed.go"
click node_planner "https://github.com/sxijyoti/whiskey/blob/main/internal/planner/dirty.go"
click node_parser "https://github.com/sxijyoti/whiskey/blob/main/internal/parser/markdown.go"
click node_frontmatter "https://github.com/sxijyoti/whiskey/blob/main/internal/parser/frontmatter.go"
click node_shortcodes "https://github.com/sxijyoti/whiskey/blob/main/internal/parser/shortcode.go"
click node_templates "https://github.com/sxijyoti/whiskey/blob/main/internal/template/render.go"
click node_template_engine "https://github.com/sxijyoti/whiskey/blob/main/internal/template/engine.go"
click node_dependency_refs "https://github.com/sxijyoti/whiskey/blob/main/internal/dependency/resolve.go"
click node_source_registry "https://github.com/sxijyoti/whiskey/blob/main/internal/source/registry.go"
click node_http_source "https://github.com/sxijyoti/whiskey/blob/main/internal/source/http.go"
click node_materializer "https://github.com/sxijyoti/whiskey/blob/main/internal/source/materialize.go"
click node_workspace "https://github.com/sxijyoti/whiskey/blob/main/internal/source/workspace.go"
click node_manifest "https://github.com/sxijyoti/whiskey/blob/main/internal/source/manifest.go"
click node_extractor "https://github.com/sxijyoti/whiskey/blob/main/internal/transform/extract.go"
click node_watcher "https://github.com/sxijyoti/whiskey/blob/main/internal/watcher/watcher.go"
click node_devserver "https://github.com/sxijyoti/whiskey/blob/main/internal/devserver/server.go"

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_config,node_graph,node_fingerprints,node_planner,node_browser toneBlue
class node_dependency_refs,node_source_registry,node_http_source,node_materializer,node_workspace,node_manifest,node_extractor toneAmber
class node_parser,node_frontmatter,node_shortcodes,node_templates,node_template_engine toneMint
class node_cli,node_watcher,node_devserver toneRose
class node_user,node_site_output,node_remote_web toneIndigo
```

## Components

### Build workflow

- [Site configuration](https://github.com/sxijyoti/whiskey/blob/main/internal/config/config.go): `internal/config/config.go`
- [Dependency graph](https://github.com/sxijyoti/whiskey/blob/main/internal/graph/builder.go): `internal/graph/builder.go`
- [Input fingerprints](https://github.com/sxijyoti/whiskey/blob/main/internal/fingerprint/changed.go): `internal/fingerprint/changed.go`
- [Dirty-page planner](https://github.com/sxijyoti/whiskey/blob/main/internal/planner/dirty.go): `internal/planner/dirty.go`

### Source synchronization

- [Include resolution](https://github.com/sxijyoti/whiskey/blob/main/internal/dependency/resolve.go): `internal/dependency/resolve.go`
- [Source providers](https://github.com/sxijyoti/whiskey/blob/main/internal/source/registry.go): `internal/source/registry.go`
- [HTTP source fetch](https://github.com/sxijyoti/whiskey/blob/main/internal/source/http.go): `internal/source/http.go`
- [Workspace materializer](https://github.com/sxijyoti/whiskey/blob/main/internal/source/materialize.go): `internal/source/materialize.go`
- [Persistent workspace](https://github.com/sxijyoti/whiskey/blob/main/internal/source/workspace.go): `internal/source/workspace.go`
- [Source cache manifest](https://github.com/sxijyoti/whiskey/blob/main/internal/source/manifest.go): `internal/source/manifest.go`
- [HTML extraction](https://github.com/sxijyoti/whiskey/blob/main/internal/transform/extract.go): `internal/transform/extract.go`

### Content rendering

- [Markdown parser](https://github.com/sxijyoti/whiskey/blob/main/internal/parser/markdown.go): `internal/parser/markdown.go`
- [Frontmatter metadata](https://github.com/sxijyoti/whiskey/blob/main/internal/parser/frontmatter.go): `internal/parser/frontmatter.go`
- [Content shortcodes](https://github.com/sxijyoti/whiskey/blob/main/internal/parser/shortcode.go): `internal/parser/shortcode.go`
- [Template renderer](https://github.com/sxijyoti/whiskey/blob/main/internal/template/render.go): `internal/template/render.go`
- [Template loading](https://github.com/sxijyoti/whiskey/blob/main/internal/template/engine.go): `internal/template/engine.go`

### CLI and development

- [CLI commands](https://github.com/sxijyoti/whiskey/blob/main/internal/cli/build.go): `internal/cli/build.go`
- [File watcher](https://github.com/sxijyoti/whiskey/blob/main/internal/watcher/watcher.go): `internal/watcher/watcher.go`
- [Live-reload server](https://github.com/sxijyoti/whiskey/blob/main/internal/devserver/server.go): `internal/devserver/server.go`

### Other components

- **Site author**
- **Generated site**
- **Browser**
- **Remote web**

## Connections

- Site author → CLI commands: runs commands (evidence: `internal/cli/build.go`)
- CLI commands → Site configuration: loads settings
- CLI commands → Dependency graph: inspects dependencies
- Dependency graph → Markdown parser: parses metadata (evidence: `internal/graph/builder.go`)
- Dependency graph → Include resolution: resolves includes (evidence: `internal/graph/builder.go`)
- Dependency graph → Source providers: resolves sources (evidence: `internal/graph/builder.go`)
- Input fingerprints → Persistent workspace: reads cached inputs (evidence: `internal/fingerprint/changed.go`)
- Dependency graph → Input fingerprints: tracks build inputs
- Input fingerprints → Dirty-page planner: reports changes
- Dirty-page planner → Dependency graph: finds affected pages (evidence: `internal/planner/dirty.go`)
- Dirty-page planner → Generated site: selects rebuilds
- Markdown parser → Frontmatter metadata: extracts metadata
- Markdown parser → Content shortcodes: expands shortcodes
- Template renderer → Template loading: loads layouts
- Template renderer → Generated site: renders pages
- Include resolution → Source providers: resolves providers
- Source providers → HTTP source fetch: creates HTTP source
- HTTP source fetch → Remote web: fetches content (evidence: `internal/source/http.go`)
- HTTP source fetch → HTML extraction: extracts HTML as Markdown (evidence: `internal/source/http.go`)
- HTML extraction → Markdown parser: parses frontmatter (evidence: `internal/transform/extract.go`)
- Workspace materializer → Persistent workspace: stores sources
- Workspace materializer → Source cache manifest: tracks cache metadata
- Persistent workspace → Template renderer: supplies render inputs
- CLI commands → File watcher: starts file watching
- CLI commands → Live-reload server: starts live serving
- File watcher → CLI commands: triggers rebuilds
- Live-reload server → Browser: serves site and reloads
- CLI commands → Workspace materializer: synchronizes sources
