demarkus-library

Sub-project hub for demarkus-library — the web front-end ("Universe Library") for a demarkus universe: a server-rendered Go + htmx reading room over a broker-fronted knowledge system. Standalone repo latebit-io/demarkus-library, own release cadence (mirrors obsidian-demarkus).

All durable knowledge about this project lives under /demarkus-library/. This hub is the discovery backstop — keep it current.

Source of truth

• Plan — Universe Library — the authoritative plan (architecture, identity model, phases 0–5, build-model strategy, resolved decisions, open questions). Fetch this first in any new session.

Sections

• Architecture — app structure, transport, MCP-client/session model, render pipeline (TBD)
• Decisions (ADRs) — one file per decision at adr/<NNNN>-<title>.md
  • ADR 0001 — Echo + bulwarkauth-style layout
  • ADR 0002 — Hexagonal (ports & adapters) architecture
  • ADR 0003 — SSR-first, htmx-hard, no JSON
• Patterns — Go + htmx + goldmark idioms, conventions (TBD)
• Debugging — bugs, gotchas, investigations (TBD)
• Roadmap / status — phase progress, what's in flight (TBD)
• Debt — technical debt, deferred work (TBD)
• Journal — session notes, one file per day at journal/<YYYY-MM-DD>.md
  • 2026-06-10 — Phase 0 + Phase 1a shipped

Status

• Phase 0 — Foundation spike: DONE (2026-06-10). A real demarkus doc renders server-side in a browser over the QUIC fetch client.
• Phase 1a — Reading room (features-first): DONE (2026-06-10). Built over the current direct-QUIC world. Routes: / (default doc), /d/<path> (document, or the stacks listing when path ends in /), /search?q= (card catalog, LOOKUP, debounced htmx, click-through), /versions/<path> (editions), /health. Link rewriting maps internal doc/dir/version links to in-app /d/<path>. htmx fragment-vs-page: targeted swaps return the content partial, boosted nav + no-JS return the full page (one render path, degrades without JS). Unit tests green; verified live against soul.demarkus.io:6309.
• Phase 1b — Library card (the turnstile): NEXT. Broker MCP-gateway outbound adapter implementing port.WorldGateway (+ org-scoped OAuth login, cookie session, tokens server-side) — swapped in at the composition root, core/web untouched. This is where the open anonymous-reads question gets resolved.
• Deferred: backlinks / "cited by" (no server verb — needs a graph crawl; plan defers the viz); world directory / floor (multi-world from the root hub).

Architecture — hexagonal (ports & adapters)

Dependencies point inward (adapters → ports → core); the core knows nothing of Echo, QUIC, or goldmark. See ADR 0002. Echo v5 + bulwarkauth idioms retained (ADR 0001).

cmd/demarkus-library/        composition root — wires adapters into the core
internal/core/
  domain/    document.go     entities + sentinel errors (no external deps)
  port/      port.go         inbound + outbound port interfaces (ReadingService; WorldGateway, Renderer)
  service/   reading.go      application core — Read/Browse/History/Search
internal/adapter/
  inbound/web/               Echo handlers/routes/view + link rewriting  (driving adapter)
  outbound/world/            demarkus QUIC fetch (Fetch/List/Versions/Lookup) → port.WorldGateway
  outbound/markdown/         goldmark + bluemonday → port.Renderer

replace directives point demarkus client/protocol at local ../demarkus. .coderabbit.yaml encodes the dependency rule as per-path review instructions.

Front-end philosophy

SSR-first, htmx-hard, no JSON — see ADR 0003. The server renders all HTML; htmx is the only interaction layer; no JSON API, no client-side state. Realized in 1a: link rewriting + linkifyCatalogPaths keep navigation server-driven; the page/content template split gives htmx fragments without a duplicate render path. htmx is vendored (web/static/htmx.min.js, pinned to the latest release — currently 2.0.10) and served from the binary — no CDN. JS islands are a last resort, each tracked as a concession in ADR 0003.

Open questions

• Does the broker expose any anonymous-readable surface? Decides whether Phase 1b hits the broker directly vs a dev world for unauthenticated reads. (See plan.) Not blocking 1a — the reading room ran over a world directly over QUIC.

Stack (decided)

Server-rendered Go (Echo v5 + html/template + htmx), goldmark + bluemonday for markdown→sanitized HTML, MCP client over the broker MCP gateway (Phase 1b+), org-scoped OIDC (auth-code/PKCE/DCR), tokens server-side only. Single Go binary, no Node build. Go 1.26.4. Build on Opus 4.8 by default; Fable 5 as the escalation valve.