Alethograph

Alethograph

3 min read

What Is It

Alethograph is a web-based research knowledge platform that serves the Obsidian Academic Research vault as a live website at alethograph.com. It runs from a Mac Mini/MacBook acting as a server, with Cloudflare handling DNS, HTTPS, and access control.

The long-term vision is an interactive research assistant: visitors can browse the knowledge graph and ask questions answered by Claude, grounded in the vault’s papers, concepts, and ideas.

Architecture

Obsidian Vault (iCloud)
       |
       | symlink
       v
   Quartz v4.5.2          Cloudflare Tunnel          Cloudflare Access
   (static site gen) ---> (cloudflared daemon) ---> (email-based auth)
   localhost:8080          encrypted tunnel           alethograph.com
       |
       | reads from
       v
  ~/.claude/research.db   (SQLite, migrating to Neo4j Aura)

Components

ComponentRoleLocation
QuartzRenders Obsidian markdown as a website with graph view, search, LaTeX~/quartz/
Cloudflare TunnelExposes localhost:8080 to the internet without opening ports~/.cloudflared/config.yml
Cloudflare AccessEmail-based authentication gate (Zero Trust)Cloudflare dashboard
launchdAuto-starts Quartz + tunnel on boot~/Library/LaunchAgents/com.alethograph.*.plist
Research DBStores paper/concept/researcher relationships~/.claude/research.db (migrating to Neo4j Aura)

Domain

  • Domain: alethograph.com (registered on Cloudflare)
  • Name origin: Greek aletheia (truth as unconcealment) + graph (writing instrument) = “truth-writing instrument”
  • Tunnel ID: e623f937-2a2b-4f8f-81c3-4d682f16bc33

Current State (Phase 1: Static Site)

What works

  • Quartz builds and serves all 537+ vault notes
  • Cloudflare tunnel routes alethograph.com and www.alethograph.com to localhost:8080
  • Cloudflare Access provides email-based authentication
  • launchd auto-restarts both services on reboot
  • Wikilinks, LaTeX (KaTeX), tags, frontmatter, graph view all render correctly

Known issues

  • 404 popups when clicking unresolved wikilinks (notes referenced but not yet created)
  • PDFs excluded from build (Files directory in ignorePatterns) — not served
  • Git date warnings (vault not tracked by git, so dates fall back to filesystem)
  • Mac must stay awake to serve (System Settings > Energy > Prevent sleep)

Configuration Files

Quartz config (~/quartz/quartz.config.ts)

  • pageTitle: “Alethograph”
  • baseUrl: “alethograph.com”
  • ignorePatterns: private, templates, .obsidian, Files
  • LaTeX via KaTeX, ObsidianFlavoredMarkdown enabled
  • SPA mode, popovers, graph view all enabled

Cloudflared config (~/.cloudflared/config.yml)

tunnel: e623f937-2a2b-4f8f-81c3-4d682f16bc33
credentials-file: /Users/osianshelley/.cloudflared/e623f937-2a2b-4f8f-81c3-4d682f16bc33.json
 
ingress:
  - hostname: alethograph.com
    service: http://localhost:8080
  - hostname: www.alethograph.com
    service: http://localhost:8080
  - service: http_status:404

Launch agents (~/Library/LaunchAgents/)

  • com.alethograph.quartz.plist — runs npx quartz build --serve in ~/quartz/, KeepAlive
  • com.alethograph.cloudflared.plist — runs cloudflared tunnel run alethograph, KeepAlive
~/quartz/content -> /Users/osianshelley/Library/Mobile Documents/com~apple~CloudDocs/Obsidian/Academic Research

Planned Phases

Phase 2: Neo4j Graph Database

  • Migrate from SQLite to Neo4j Aura (cloud graph DB)
  • Enables sharing the knowledge graph with collaborators
  • Plan documented in ~/.claude/plans/concurrent-sniffing-lollipop.md
  • Nodes: Paper, Concept, Researcher, Book, Idea, Topic
  • Relationships: STUDIES, KNOWS, DERIVED_FROM, EVIDENCED_BY, etc.

Phase 3: Interactive Research Assistant

  • Chat interface on alethograph.com where visitors can query the vault
  • Backend calls Claude API with vault content as context
  • Answers grounded in papers/concepts with wikilink citations
  • Powered by the same logic as /researcher-* skills
  • Key decisions needed:
    • API cost model (who pays for Claude calls?)
    • Depth of answers (simple Q&A vs full researcher-level)
    • Neo4j integration for graph-powered retrieval

How to Operate

Start manually

cd ~/quartz && npx quartz build --serve &
cloudflared tunnel run alethograph &

Check status

curl -s -o /dev/null -w "%{http_code}" http://localhost:8080  # should be 200
launchctl list | grep alethograph  # check launch agents

Rebuild after vault changes

Quartz watches for file changes in --serve mode. If it doesn’t pick up a change, restart:

launchctl kickstart -k gui/$(id -u)/com.alethograph.quartz

View logs

tail -f /tmp/quartz.log
tail -f /tmp/cloudflared.log

project

Graph View