Skip to content

Add: docs/HLD.md, the high-level design, with its diagrams on Pages - #24

Merged
0xLeif merged 1 commit into
mainfrom
docs/hld-mermaid
Sep 26, 2026
Merged

0xLeif merged 1 commit into
mainfrom
docs/hld-mermaid

Conversation

@0xLeif

@0xLeif 0xLeif commented Sep 26, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Adds docs/HLD.md, a high-level design written from the code: purpose, context, components, key flows, data, runtime and deployment, trust boundaries, failure modes, decisions and a glossary. It links DECISIONS.md and HI-1.md rather than restating them, and marks what this repository cannot answer as Unknown: (the Homebrew tap and the corvidlabs.xyz docs site both live elsewhere).
  • 12 Mermaid diagrams: context, modules, argv routing, sequence diagrams for capture, retire, export and the fledge plugin and its hooks, the INTENT.md feature-list rewrite, how parse_body classifies a line, a state diagram of an id's standing (not a lifecycle, per DECISIONS 搂5), the in-memory model, and build, release and Pages.
  • Pages: pages.yml now also renders the HLD to /architecture/. It converts the markdown with a pinned marked and splices it into docs/site/architecture.html, which draws the diagrams with Mermaid from jsdelivr, fixes relative links to point at GitHub, and gives headings GitHub-style ids. It is a separate page on purpose: the hi view intent page fetches nothing (VIEW-2), so Mermaid does not belong in hi's renderer, and index.html, intent.html and intent.json are unchanged. The path filter adds docs/HLD.md and docs/site/**.
  • README: a short Architecture section with one overview diagram and links to the HLD and the live page. Nothing else in the README changed.
  • No source, test, spec or hi/ changes. hi/ already existed, so only hi check was run.

Test Plan

  • fledge lanes run verify passes (fmt, clippy, 229 tests, view-behaves 14 checks, intent, index, specsync 10/10, nudge-behaves, plugin validate)
  • hi check: 168 criteria, 10 families, 7 files, 2 retired, no problems, no notes
  • Every diagram in docs/HLD.md (12) and README.md (1) renders with mmdc, with no syntax-error output
  • The Pages render step, run locally (the awk splice also under Ubuntu's mawk in Docker, byte-identical): 12 SVGs drawn in headless Chrome, no horizontal overflow at 375px or 1280px, and zero axe violations (WCAG 2.1 A/AA and best practice) in light and dark
  • actionlint passes on pages.yml
  • After merge: the Pages run succeeds and https://corvidlabs.github.io/hi/architecture/ shows the diagrams

馃 Generated with Claude Code

https://claude.ai/code/session_01V3ZZAEiUP7xRJPozhZb6rL

docs/HLD.md describes how hi works end to end, from the code: argv
routing, capture, retire and export as sequence diagrams, how HI/1 is
parsed, the id rules, an id's standing as a state diagram, how the
INTENT.md list is regenerated, the fledge plugin and its hooks, build
and release, trust boundaries, and failure modes. Twelve Mermaid
diagrams, all rendered with mermaid-cli before committing.

The Pages site gains /architecture/: pages.yml converts the markdown
with a pinned marked and splices it into docs/site/architecture.html,
which draws the diagrams with Mermaid from jsdelivr. It is a separate
page on purpose, because the hi view page fetches nothing (VIEW-2).

The README gains a short Architecture section with one overview
diagram and links to both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V3ZZAEiUP7xRJPozhZb6rL
@0xLeif
0xLeif merged commit a65a4a1 into main Sep 26, 2026
9 checks passed
@0xLeif
0xLeif deleted the docs/hld-mermaid branch September 26, 2026 03:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant