Overview

Executive Summary

quill.md is a client-side-only Single-Page Application (SPA) built for managing project issues stored directly in a Git repository as plain Markdown files with YAML frontmatter.

The application follows a strictly layered architecture separating UI, State (Svelte Runes), Domain Services, and I/O Adapters. It supports two primary execution modes:

Local Edit Mode: Uses the browser's File System Access (FSA) API to read/write directly to a local directory on disk.
Remote Edit Mode: Uses the Strategy pattern to communicate with Git hosting providers (GitHub, GitLab) via their REST APIs, pulling the.quill.md/ subtree and writing commits directly to an orphan branch.

No Backend Required

Though primarily a static SPA with no mandatory backend, the repository includes two auxiliary backend components for optional advanced features: a local Hocuspocus server for CRDT-based real-time collaboration, and an MCP Server for LLM integration.

Core Principles

The architecture is built on the following constraints:

Zero Lock-in: Data must always be accessible as standard Markdown.
Offline-First: Local edit mode operates with zero network requests.
Optimistic UI: Remote writes are executed optimistically using direct API calls, queuing operations in a debounced Commit Queue.

Repository Anatomy

The codebase is organized into distinct domain areas to ensure separation of concerns.

/
├── src/
│   ├── routes/          # SvelteKit pages and layouts (+page.svelte, +layout.svelte)
│   ├── lib/
│   │   ├── adapters/    # I/O layer (LocalFsAdapter, RemoteWritableAdapter)
│   │   ├── collab/      # CRDT/Yjs integration for realtime collaboration
│   │   ├── components/  # Reusable UI components
│   │   ├── services/    # Pure domain logic (Parsers, Serializers)
│   │   ├── state/       # Application state (Svelte Runes)
│   │   ├── types/       # TypeScript domain types
│   │   └── ui/          # UI Primitive components (Cards, Buttons, Inputs)
├── server/              # Hocuspocus WebSockets backend for Yjs sync
├── quill-mcp-server/    # Model Context Protocol server exposing issues to LLMs
└── tests/               # Vitest and Playwright test suites