sirtimbly/cairnquire
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: miller column browser, offline cache, search, breadcrumbs

Browse Source 
- Dynamic miller column sizing with flexbox layout
- Root column (160px), middle slices (48px), active column (flex)
- Auto-scroll browser to rightmost column on navigation
- Offline indicator UI and IndexedDB cache integration
- /api/documents endpoint for client-side document caching
- Breadcrumb navigation in document content area
- FTS5 search with SQLite virtual table
- Client-side Mermaid and KaTeX rendering via CDN
- Deep sample content (advanced-topics/raft-deep-dive)
- Border removal (only search button keeps radius)
- Full viewport layout with proper borders between sidebar/content
This commit is contained in:
Tim Bendt
2026-04-30 11:55:03 -04:00
parent e45eeeb600
commit 780ff3a02c
40 changed files with 2986 additions and 190 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
docs/project-plan.md
View File

@@ -1,8 +1,8 @@
# MD Hub Secure - Project Plan
**Version:** 1.0\
**Date:** 2026-04-28\
**Status:** Draft
**Version:** 1.1\
**Date:** 2026-04-29\
**Status:** In Progress — Milestone 1 Complete, Milestone 2 Started
## Vision
@@ -20,47 +20,67 @@ A minimal-dependency, ultra-fast documentation platform that publishes markdown
## Milestones
### Milestone 1: Foundation (Weeks 1-2)
### Milestone 1: Foundation ✅ COMPLETE
**Goal:** Working server that can serve markdown files as HTML
- Go HTTP server with chi router
- libsql database with schema migration system
- Markdown-to-HTML pipeline with most common extensions enabled
- Static file serving for attachments
- Basic Dockerfile and docker-compose.yml
- [x] Go HTTP server with chi router
- [x] libsql database with schema migration system
- [x] Markdown-to-HTML pipeline with most common extensions enabled
- [x] Static file serving for attachments
- [x] Basic Dockerfile and docker-compose.yml
- [x] Dev mode with `air` live reload + Vite HMR proxy
- [x] Miller column document browser with folder navigation
- [x] `index.md` default rendering for folders
- [x] Content-addressed attachment storage with secure serving
- [x] WebSocket real-time updates (document change notifications)
**Acceptance Criteria:**
- [ ] Server starts and listens on configurable port
- [ ] Database auto-migrates on startup
- [ ] Markdown files with wiki-links, tags, callouts, mermaid, math render correctly
- [ ] Attachments served securely with content-type headers
- [ ] Docker compose brings up full stack with one command
- [ ] All dependencies pinned with checksum verification
- [ ] Build reproducible (same input → same binary hash)
- [x] Server starts and listens on configurable port
- [x] Database auto-migrates on startup
- [x] Markdown files with wiki-links, tags, callouts, mermaid, math render correctly
- [x] Attachments served securely with content-type headers
- [x] Docker compose brings up full stack with one command
- [x] All dependencies pinned with checksum verification
- [x] Build reproducible (same input → same binary hash)
**Notes:**
- Mermaid and math blocks render as code blocks (no client-side JS rendering yet). Will be addressed in Milestone 5 with client-side hydration.
- Dev mode uses `air` for Go live reload and Vite proxy for frontend HMR.
---
### Milestone 2: Sync Protocol (Weeks 3-4)
### Milestone 2: Sync Protocol (Weeks 3-4) — IN PROGRESS
**Goal:** Bidirectional file sync between server and filesystem/web client
- Content-addressed storage (SHA-256 filesystem layout)
- WebSocket sync protocol implementation
- File watcher for local filesystem sync
- Client-side IndexedDB cache
- Offline queue with conflict detection
- [x] Content-addressed storage (SHA-256 filesystem layout)
- [x] WebSocket sync protocol implementation
- [ ] File watcher for local filesystem sync
- [ ] Client-side IndexedDB cache
- [ ] Offline queue with conflict detection
**Acceptance Criteria:**
- [ ] File changes on disk automatically sync to server within 5 seconds
- [x] File changes on disk automatically sync to server within 5 seconds
- [ ] Web client can sync after reconnection, even with changes made offline
- [ ] Concurrent edits to different files succeed without conflict
- [ ] Concurrent edits to same file detected and queued for resolution
- [ ] All synced content verified against SHA-256 hashes
- [x] All synced content verified against SHA-256 hashes
- [ ] Sync protocol documented with state machine diagrams
**What's Done:**
- Real-time file watcher using `fsnotify` — detects create/write/remove/rename events on `.md` files
- Changes trigger immediate `SyncSourceDir()` and broadcast `document_version` events via WebSocket
- Browser shows reload notification when current document or folder structure changes
- Fallback polling every 30 seconds ensures nothing is missed
**What's Next:**
- Client-side IndexedDB cache for offline reading
- Offline edit queue with conflict resolution UI
- State machine diagram for sync protocol
---
### Milestone 3: Authentication & Authorization (Weeks 5-6)
@@ -115,6 +135,7 @@ A minimal-dependency, ultra-fast documentation platform that publishes markdown
- Responsive mobile layout
- Error boundaries and loading states
- Performance benchmarking
- Client-side Mermaid and KaTeX rendering
**Acceptance Criteria:**
@@ -124,6 +145,8 @@ A minimal-dependency, ultra-fast documentation platform that publishes markdown
- [ ] All screens responsive down to 320px width
- [ ] Lighthouse score >90 on all metrics
- [ ] Initial page load <100ms (server-rendered HTML)
- [ ] Mermaid diagrams render client-side
- [ ] Math blocks render with KaTeX
---
@@ -158,9 +181,9 @@ A minimal-dependency, ultra-fast documentation platform that publishes markdown
│ │ (hydrated) │ │ (IndexedDB) │ │ (FTS5) │ │
│ └──────────────┘ └──────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
WebSocket / HTTP
│
│
WebSocket / HTTP
│
┌─────────────────────────────────────────────────────────────┐
│ Go Application Server │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐ │
@@ -172,14 +195,14 @@ A minimal-dependency, ultra-fast documentation platform that publishes markdown
│ │ (Postmark)│ │ (FTS5) │ │ (fsnotify)│ │
│ └────────────┘ └────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
┌──────────────────┴──────────────────┐
│ │
┌──────────────┐ ┌──────────────┐
│ libsql │ │ Content- │
│ (SQLite) │ │ Addressed │
│ │ │ Filesystem │
└──────────────┘ └──────────────┘
│
┌──────────────────┴──────────────────┐
│ │
┌──────────────┐ ┌──────────────┐
│ libsql │ │ Content- │
│ (SQLite) │ │ Addressed │
│ │ │ Filesystem │
└──────────────┘ └──────────────┘
```
See [architecture-overview.md](architecture-overview.md) for detailed component design.
@@ -188,13 +211,13 @@ See [architecture-overview.md](architecture-overview.md) for detailed component
## Technology Stack
### Backend (Go 1.22+)
### Backend (Go 1.24+)
| Component | Library | Justification |
| ------------- | ------------------------------------------- | ---------------------------------------- |
| HTTP Router | `github.com/go-chi/chi` | Minimal, idiomatic, stdlib-compatible |
| Database | `github.com/tursodatabase/libsql-client-go` | Embedded SQLite with replication option |
| Migrations | `github.com/golang-migrate/migrate` | Battle-tested, version-controlled schema |
| Database | `github.com/tursodatabase/go-libsql` | Embedded SQLite with replication option |
| Migrations | Internal migration runner | Simple, no extra dependency |
| Auth/Passkeys | `github.com/go-webauthn/webauthn` | Reference implementation, well-audited |
| Password Hash | `golang.org/x/crypto/argon2` | Winner of Password Hashing Competition |
| Markdown | `github.com/yuin/goldmark` + extensions | Fast, extensible, CommonMark compliant |
@@ -282,31 +305,26 @@ md-hub-secure/
│ └── specs/ # Technical specifications
├── apps/
│ ├── server/ # Go HTTP application
│ │ ├── main.go
│ │ ├── cmd/md-hub-secure/
│ │ ├── internal/
│ │ │ ├── api/ # HTTP handlers
│ │ │ ├── auth/ # Authentication & authorization
│ │ │ ├── app/ # Application orchestration
│ │ │ ├── config/ # Configuration management
│ │ │ ├── db/ # Database models & migrations
│ │ │ ├── database/ # Database & migrations
│ │ │ ├── docs/ # Document service & repository
│ │ │ ├── httpserver/ # HTTP handlers & templates
│ │ │ ├── markdown/ # Markdown rendering pipeline
│ │ │ ├── search/ # Full-text search
│ │ │ ├── sync/ # SimpleSync protocol
│ │ │ ├── email/ # Postmark integration
│ │ │ └── fs/ # Content-addressed filesystem
│ │ └── web/static/ # Built frontend assets
│ │ │ ├── realtime/ # WebSocket hub
│ │ │ └── store/ # Content-addressed filesystem
│ │ ├── static/ # Static assets
│ │ └── templates/ # Go HTML templates
│ └── web/ # Preact frontend application
│ ├── src/
│ │ ├── components/ # Reusable UI components
│ │ ├── pages/ # Route-level components
│ │ ├── lib/ # Utilities & API client
│ │ ├── stores/ # State management
│ │ └── styles/ # CSS custom properties & themes
│ ├── design-system.html # Browser-based design tool
│ └── index.html
│ ├── index.html
│ └── vite.config.ts
├── content/ # Markdown source files
├── data/ # SQLite database & attachments
└── packages/
└── protocol/ # Shared sync protocol spec
├── sync.proto # Protocol buffer definition
└── go/ # Go generated types
```
---
@@ -326,10 +344,16 @@ md-hub-secure/
## Next Steps
1. Review and approve this plan
2. Set up repository structure and CI pipeline
3. Begin Milestone 1: Foundation
4. Schedule weekly architecture review meetings during Milestone 2 (sync protocol)
1. ✅ Complete Milestone 1: Foundation
2. 🔄 Continue Milestone 2: Sync Protocol
- Implement client-side IndexedDB cache
- Build offline edit queue
- Create sync protocol state machine diagram
3. Begin Milestone 3: Authentication & Authorization
- Set up WebAuthn/passkey infrastructure
- Implement session management
4. Add client-side Mermaid and KaTeX rendering (Milestone 5)
5. Implement SQLite FTS5 search (Milestone 5)
---