hermes-wiki-static/docs/ARCHITECTURE.md

Architecture

Why this fork exists

DanielCheer/obsidian-web-viewer is a great single-file Obsidian-vault viewer (server.py + vault.html, ~10 KB + 14 KB, Python stdlib only). But for Lukas' Hermes Wiki workflow — 245 Markdown files across 18 top-level folders, frequent cross-referencing via WikiLinks, mobile reading — three specific UX gaps needed fixing:

1. 3D Graph shows all nodes uniformly — no indication of which node the user is currently reading or which nodes are connected to it
2. Layout breaks on small screens — the 3-panel grid (280px 1fr 260px) is too narrow on 13" laptops and unusable on phones
3. Click-to-navigate from graph — Three.js canvas accepts clicks but doesn't trigger navigation

Design principles

1. Additive layer, not fork-and-modify

We modify exactly one line in vault.html (a <script src="vault-custom.js"></script> tag before </body>). Everything else — including the customizations themselves — lives in vault-custom.js.

Why:

• Upstream git pull conflicts are trivial to resolve (the one line is recognizable)
• Customizations are clearly separated from upstream code
• Reviewing customizations is reading one file, not diffing the whole repo
• Easier to upstream-merge back if Lukas' features prove generally useful

2. HermesCustom namespace

All custom code lives under window.HermesCustom. Methods are namespaced and self-documenting:

window.HermesCustom = window.HermesCustom || {};
HermesCustom.highlightCurrentNode = function() { ... };
HermesCustom.setupGraphClickHandler = function() { ... };
HermesCustom.responsiveLayout = function() { ... };

This way the namespace is visible in DevTools and a future maintainer can see at a glance what's custom vs. upstream.

3. Server.py stays mostly upstream

We add one enhancement to server.py: a ?file=<path> query parameter that returns the file directly (used by HermesCustom.highlightCurrentNode to know which file is open). This is a 5-line change that doesn't conflict with any upstream logic.

If upstream adds a similar feature, we drop our addition.

File map

hermes-wiki-viewer/
├── server.py                # obv-fork + 5 lines (file-query-param)
├── vault.html               # obv-fork + 1 line (script tag for custom.js)
├── vault-custom.js          # ALL Lukas-specific code
├── requirements.txt         # PyYAML only (same as upstream)
├── README.md                # this repo's entry point
├── LICENSE                  # MIT (inherited)
├── CHANGELOG.md             # release notes for Lukas-additions
├── docs/
│   ├── ARCHITECTURE.md      # you are here
│   └── CUSTOMIZATIONS.md    # spec for each Lukas-feature
└── .gitignore               # standard

Why we keep vault-custom.js separate from vault.html

Embedding customizations into vault.html would mean:

• Every upstream update requires re-applying the entire diff
• Reviewing customizations requires diffing two HTML files
• Conflicts when upstream renames a function we override

A separate file means:

• The customizations are a stable, reviewable unit
• Upstream updates touch vault.html only, customizations are unchanged
• The one-line patch in vault.html is a clear "anchor point" that any reviewer can understand

Why Python stdlib only (no Flask/FastAPI)

Upstream uses http.server from stdlib. We keep this. Adding a framework would:

• Inflate dependencies
• Require version-pinning for reproducibility
• Make the tool harder to deploy (anywhere with Python 3.8+ works)

The 5-line addition to server.py is plain stdlib BaseHTTPRequestHandler style.

Tradeoffs we accepted

• No build step. Customizations are vanilla JS. No bundler, no TypeScript. Means no static type-checking, but means anyone can read and modify the code without toolchain setup.
• No tests in CI. We rely on manual testing for now. CI tests would add complexity that doesn't match the project's "simple tool" character. (Future: a small Playwright test for the graph highlighting.)
• No auto-update from upstream. When obv updates, Lukas has to git pull upstream && git merge. The one-line vault.html patch needs re-application if upstream modified it. This is acceptable for a personal side-project.

Roadmap

See CHANGELOG.md for planned additions. Current priorities:

1. ✅ Current-page highlighting in 3D Graph
2. ✅ Click-to-navigate on graph
3. ✅ Responsive layout (1024px and 768px breakpoints)
4. ⏳ Backlinks panel (per-page incoming WikiLinks)
5. ⏳ Keyboard shortcuts (j/k for next/prev file, [/] for nav, g/G for graph focus)
6. ⏳ Light theme variant (currently Catppuccin-dark only)