Resumen

Resumen Ejecutivo

quill.md es una Single-Page Application (SPA) ejecutada puramente en el cliente, construida para gestionar issues de proyectos guardados directamente en un repositorio Git como archivos Markdown con frontmatter YAML.

La aplicación sigue una arquitectura de capas estricta que separa la UI, el Estado (Svelte Runes), los Servicios de Dominio y los Adaptadores I/O. Soporta dos modos principales de ejecución:

Modo Edición Local: Usa la API File System Access (FSA) del navegador para leer/escribir directamente en un directorio local del disco.
Modo Edición Remota: Usa el patrón Strategy para comunicarse con proveedores de Git (GitHub, GitLab) a través de sus APIs REST, haciendo pull de la carpeta .quill.md/ y escribiendo commits directamente en una rama huérfana.

Sin Backend Obligatorio

Aunque es principalmente una SPA estática sin backend obligatorio, el repositorio incluye dos componentes backend auxiliares para características avanzadas opcionales: un servidor local Hocuspocus para colaboración en tiempo real basada en CRDT, y un Servidor MCP para integración con LLMs.

Principios Clave

La arquitectura está construida sobre las siguientes restricciones:

Cero Vendor Lock-in: Los datos siempre deben ser accesibles como Markdown estándar.
Offline-First: El modo de edición local opera con cero peticiones de red.
Actualizaciones Optimistas: Las escrituras remotas se ejecutan de manera optimista mediante llamadas directas a la API, encolando operaciones en una Cola de Commits "debounced".

Anatomía del Repositorio

El código base está organizado en áreas de dominio distintas para garantizar la separación de responsabilidades.

/
├── src/
│   ├── routes/          # Páginas y layouts de SvelteKit (+page.svelte, +layout.svelte)
│   ├── lib/
│   │   ├── adapters/    # Capa I/O (LocalFsAdapter, RemoteWritableAdapter)
│   │   ├── collab/      # Integración CRDT/Yjs para colaboración en tiempo real
│   │   ├── components/  # Componentes UI reutilizables
│   │   ├── services/    # Lógica de dominio pura (Parsers, Serializadores)
│   │   ├── state/       # Estado de la aplicación (Svelte Runes)
│   │   ├── types/       # Tipos de dominio TypeScript
│   │   └── ui/          # Componentes primitivos (Cards, Buttons, Inputs)
├── server/              # Servidor WebSockets Hocuspocus para sincronización Yjs
├── quill-mcp-server/    # Servidor Model Context Protocol que expone los issues a LLMs
└── tests/               # Suites de pruebas con Vitest y Playwright