architecture / where-things-live

architecture / where-things-live

Where things live

v0.12.0 · 02 / 05 · 2 min read · docs/ARCHITECTURE.md

One package main at the root (the reader), plus the docs site and the

PathWhat
main.goCLI entry: flags → config → runTUI, --md/pipe output (NO_COLOR aware), --update, --mcp, --eval
cli.gothe flag table (parseArgs is driven by flagDefs)
config.goConfig, defaults, commented TOML load/save, normalize
fetch.gofetchURL (final URL, retry, readable errors), load, loadFrom, loadWith, charset → UTF-8
convert.gomedia-type dispatch, HTML → Markdown, sanitize, stripLinks
extract.goroot picking, chrome and hidden dropping, headings, anchors/cards, code lines, table flattening, crumbs, dedupe
shell.goJS-shell detection, the page’s own summary (collectHints), the notice, advertised text versions
headless.go, headless_unix.go, headless_windows.gorendering a shell page with an installed Chromium/Chrome (process group, cap, counter for the UI)
guess.gothe conservative, labelled code-language guesser
update.go, update_ui.gothe update check, the verified self-update, the release notes; the update window, footer chip and menu entry
render.goMarkdown → ANSI, Doc, LinkSpan, link positions
nav.goinput resolution, link resolution, the start page
browse.gonavigation, links/focus/hints, address bar, history and bookmark panels
tui.gothe model: Update, View/render, geometry, scroll, footer, toasts
keys.goactions, default bindings, keymap build/override
search.goin-page search (smart-case) and highlight spans
selection.gomouse selection, Y code-block copy, OSC 52 + external clipboard
overlays.go, settings.go, theme.go, style.go, anim.go, braille.gopanels, live settings, palette, SGR, springs, glyphs
panelfilter.gothe / filter shared by the menu, Settings, shortcuts and the section index (m.sel stays the real index; the selection steps over hidden entries)
store.go, cache.gohistory/bookmarks JSON; the sha256-keyed Markdown cache
page_memory.go, render_cache.gothe session page LRU and the rendered-document LRU
mcp*.go, eval.gothe agent harness: MCP server, headless sessions, eval scenarios
web/the docs site (Astro, separate build)
docs/guide, the web edition, QA reports, benchmarks, this file
scripts/QA corpora and probes, bench.sh + bench_compare.py, release, hooks

State on disk

WhatPathFormat
config~/.config/wr/config.toml (os.UserConfigDir)commented TOML, atomic write, 0644
cache~/.cache/wr/ (os.UserCacheDir)one file per page: wr-cache 2 <unix> <src> + Markdown, 0600
history~/.local/state/wr/history.jsonl (XDG_STATE_HOME)one JSON object per visit ({"u","t","a"}), 0600
bookmarks~/.local/state/wr/bookmarks.jsonJSON array, 0600
update memory~/.local/state/wr/update.json{checked, failed, latest, notified, seen}, 0600

State is hand-rolled XDG (XDG_STATE_HOME), config and cache use Go’s os.User*Dir (which honor XDG_CONFIG_HOME/XDG_CACHE_HOME on Linux). Directories are 0700. Every per-user path is read lazily per call, so tests and benchmarks redirect all three with environment variables and nothing else (isolateAll in tui_test.go, benchIsolate in bench_test.go).

edit this page on GitHub ↗report a problem ↗