140 lines
6.3 KiB
Markdown
140 lines
6.3 KiB
Markdown
# Personal Knowledge Manager (PKM) — Concrete Backlog
|
|
|
|
Scope for v1 (agreed)
|
|
- Single vault folder on disk (user-provided path).
|
|
- Files are Markdown with YAML front matter; Obsidian-compatible (front matter, [[WikiLinks]], relative links, optional inline #tags).
|
|
- Flask backend; Tailwind + DaisyUI frontend; server-rendered pages with light JS.
|
|
- CodeMirror 6 editor from the start.
|
|
- Search/index via SQLite FTS5 stored under .kb/index.sqlite within the vault.
|
|
- No Git versioning and no graph view in v1 (reserved for later).
|
|
|
|
Non-goals for v1
|
|
- Multi-user auth, sync, remote deployment concerns.
|
|
- Git auto-commit/history UI.
|
|
- Graph visualization.
|
|
- Plugin system.
|
|
|
|
Definitions and conventions
|
|
- Note file naming: slugified from title, e.g., `notes/event-sourcing-overview.md`.
|
|
- Front matter includes: id (UUID), title, created, updated; optional aliases, tags, status, summary, template.
|
|
- Backlinks stored in index (not written into files).
|
|
- [[WikiLinks]] resolve by title/alias/slug; Markdown links preserved and resolved relatively.
|
|
- Vault internals live under `<vault>/.kb/` (SQLite index, config, cache).
|
|
|
|
Milestone 0 — Project scaffolding
|
|
- Tasks
|
|
- Initialize Flask app scaffolding and configuration.
|
|
- Tailwind + DaisyUI build pipeline via Tailwind CLI.
|
|
- Base Jinja templates and minimal layout with DaisyUI theme.
|
|
- Environment/config management (vault path, debug).
|
|
- Acceptance criteria
|
|
- App starts with `flask run` (or a `python -m` entrypoint).
|
|
- Tailwind builds and serves CSS; DaisyUI classes render correctly.
|
|
- Config reads vault path from env/config and shows a welcome page.
|
|
|
|
Milestone 1 — Vault and note model
|
|
- Tasks
|
|
- Filesystem repository for notes (read/write Markdown + YAML front matter).
|
|
- Create new note with required metadata; slugify filenames from `title`.
|
|
- Validate and normalize metadata (UUID, ISO timestamps).
|
|
- Resolve note identity by `id` independent of filename changes.
|
|
- Acceptance criteria
|
|
- Can create a note; it is saved to disk with valid front matter.
|
|
- Can read an existing note and get parsed metadata + body.
|
|
- Tests for slug generation and metadata normalization.
|
|
|
|
Milestone 2 — Rendering and viewing
|
|
- Tasks
|
|
- Markdown rendering via markdown-it-py with plugins (tables, task lists, footnotes, admonitions).
|
|
- HTML sanitization (bleach) with a safe allowlist.
|
|
- Obsidian-compatible rendering: [[WikiLinks]] clickable, resolve to note routes; render relative links and attachments; optionally parse inline #tags.
|
|
- Basic note view page: title, metadata pills (tags/status), content, attachments preview.
|
|
- Acceptance criteria
|
|
- Visiting a note route renders sanitized HTML.
|
|
- [[WikiLinks]] and relative links resolve; unknown links are indicated.
|
|
- Attachment links/images load from the vault.
|
|
|
|
Milestone 3 — Editor with CodeMirror 6
|
|
- Tasks
|
|
- Note edit page using CodeMirror 6 (Markdown extensions, basic shortcuts).
|
|
- Front matter editor (simple form for title/tags/status; syncs with file).
|
|
- Save flow: update `updated`; create if new; optimistic UI.
|
|
- Drag-and-drop/paste image => save under `attachments/` and insert relative path.
|
|
- Acceptance criteria
|
|
- Can create, edit, and save notes from the browser.
|
|
- Pasting/dragging an image adds a file and inserts a link.
|
|
- Title change updates slug/filename on save (see Milestone 6 for link rewrites).
|
|
|
|
Milestone 4 — Indexing and search (SQLite FTS5)
|
|
- Tasks
|
|
- SQLite schema under `<vault>/.kb/index.sqlite`.
|
|
- Initial indexing pass: ingest existing notes (title, body, tags, path, id).
|
|
- File watching (watchdog) for incremental index updates on add/edit/delete/rename.
|
|
- Search API with filters (q=, tag=, status=, path=) and boosting (title > tags > body).
|
|
- Search UI with instant results (debounced) and simple filters.
|
|
- Acceptance criteria
|
|
- Searching returns relevant notes quickly.
|
|
- Edits trigger index updates without manual rebuild.
|
|
- Tag list and per-tag results available.
|
|
|
|
Milestone 5 — Links and backlinks
|
|
- Tasks
|
|
- Outbound link extraction (Markdown links + [[WikiLinks]]); store in index.
|
|
- Backlinks computation and storage; display backlinks in note view.
|
|
- Handle aliases/title collisions deterministically (id/slug precedence).
|
|
- Acceptance criteria
|
|
- Each note shows backlinks (with context snippet if available).
|
|
- Creating a link updates backlinks after save.
|
|
|
|
Milestone 6 — Rename/move and link maintenance
|
|
- Tasks
|
|
- Rename/move note (on title or folder change): update slug/path on disk.
|
|
- Inbound link rewrite: update Markdown files that link to the old path/slug.
|
|
- Safe operations (backup to temp, atomic writes) and dry-run option (internal).
|
|
- Acceptance criteria
|
|
- Renaming a note updates its filename and maintains working links in other notes.
|
|
- Index reflects new paths; no broken links in backlinking notes.
|
|
|
|
Milestone 7 — UX polish
|
|
- Tasks
|
|
- Command palette / quick open (fuzzy search) and keyboard shortcuts.
|
|
- DaisyUI theme switch (light/dark/system) and remember preference.
|
|
- Empty states, loading states, toasts for save operations.
|
|
- Acceptance criteria
|
|
- Keyboard-driven navigation works end-to-end.
|
|
- Theme switch persists and is applied.
|
|
|
|
Milestone 8 — Packaging and quality
|
|
- Tasks
|
|
- CLI launcher: `pkm run --vault /path/to/vault` (or `python -m pkm`).
|
|
- Basic error pages and diagnostics (e.g., FTS5 availability, permission errors).
|
|
- Unit tests for core services (parsing, indexing, link rewrite).
|
|
- Minimal Dockerfile (optional) for local use with volume mount.
|
|
- Acceptance criteria
|
|
- One-command startup with vault path.
|
|
- Tests for core logic pass in CI (if configured).
|
|
|
|
Deferred items (post-v1)
|
|
- Git auto-commit/history and diffs.
|
|
- Graph view.
|
|
- Auth for remote hosting.
|
|
- Templates/daily notes generator; import/export UI; plugin hooks.
|
|
|
|
Risks and mitigations
|
|
- FTS5 availability: detect and warn at startup; fall back to basic search read-path if unavailable (optional).
|
|
- Large vault performance: chunked indexing, debounced file watcher, background tasks with status UI.
|
|
- Link rewrite safety: transactional writes with backups; verify before replace.
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
A[Vault] -->|Parse| B[Note Model]
|
|
B --> C[Render Markdown]
|
|
B --> D[Index FTS5]
|
|
D --> E[Search API/UI]
|
|
B --> F[Link Extract]
|
|
F --> G[Backlinks]
|
|
B --> H[Editor (CM6)]
|
|
H -->|Save| A
|
|
H -->|Save| D
|
|
H -->|Save| F
|
|
``` |