Shard: git-backed, graph-aware notes

Shard is a personal project: a self-hosted, Obsidian-style notes backend. Notes are plain markdown files with YAML frontmatter, stored in git repositories, and the graph of [[wikilinks]] between them is a first-class resource you can query through an API. The repo is private, so this page is the tour.

What it is

• An API-first notes service: create, read, update and delete notes over HTTP, with optimistic concurrency so two editors cannot silently clobber each other.
• Content lives in git, not in a database. A vault is just a repository of markdown files, so it stays readable (and greppable) without Shard running.
• Links between notes are parsed out of the markdown and kept as a graph, so questions like "what links here?" are an API call instead of a full-text search.
• Several independent vaults can sit behind one API.

Architecture

The backend is Go with Gin, using go-git for storage and goldmark for markdown and frontmatter parsing. Note content lives in git repositories on disk; tags, audit records and webhook state go in SQLite by default (zero config) or PostgreSQL. Events flow through an embedded NATS JetStream, so there is no external broker to run. Tracing, metrics and structured logs come from OpenTelemetry, Prometheus and zap.

Interesting bits

• Edits land as git commits, GPG-signed for integrity. Version history, per-note history browsing and restore-to-any-version come for free.
• Graph queries cover backlinks, outlinks, N-hop neighbours, shortest path between two notes, orphan detection, cycle detection and clustering.
• A write buffer batches commits, so a burst of edits does not turn into a burst of tiny commits.
• Webhooks are HMAC-SHA256 signed, with circuit breakers, rate limiting, delivery history and a dead-letter queue for the ones that keep failing.
• Live updates arrive over WebSocket, with subscriptions per note, per repository, for the graph or for system events.
• The frontend is a CodeMirror editor with vim mode, alongside a D3 force-directed graph view, daily notes, a timeline, a tag browser, and offline support as a PWA.

How it ships

CI runs the Go tests under the race detector, scans with govulncheck, gosec and Trivy, validates the API against its OpenAPI contract, and runs Playwright end-to-end tests, k6 load tests and smoke tests against a throwaway kind cluster. Releases build multi-arch container images that are cosign-signed with SBOMs attached, and Flux GitOps deploys them onto the homelab cluster on the server rack.

Timeline

• Dec 2025 - Started
• Mar 2026 - v0.1.0
• May 2026 - v0.1.1