125 lines
5.5 KiB
Markdown
125 lines
5.5 KiB
Markdown
# Initial Directory Structure
|
|
|
|
This is the proposed repository structure (application code), plus expected vault layout on disk.
|
|
|
|
Repository tree
|
|
```
|
|
.
|
|
├─ app/
|
|
│ ├─ __init__.py # Flask app factory and Jinja/Tailwind integration
|
|
│ ├─ config.py # Config: vault path, debug flags, security, etc.
|
|
│ ├─ routes/
|
|
│ │ ├─ notes.py # List/view/create/edit/delete notes; rename/move
|
|
│ │ ├─ search.py # Search endpoints (JSON + HTML)
|
|
│ │ ├─ tags.py # Tags listing and per-tag view
|
|
│ │ ├─ attachments.py # Upload/serve attachments
|
|
│ │ └─ api.py # JSON APIs (if split from HTML routes)
|
|
│ ├─ services/
|
|
│ │ ├─ vault.py # Vault path mgmt, discovery, .kb paths
|
|
│ │ ├─ notes_fs.py # Read/write Markdown + YAML; slugging; UUID mgmt
|
|
│ │ ├─ renderer.py # Markdown-it-py + bleach sanitization
|
|
│ │ ├─ indexer.py # SQLite FTS5 schema + indexing + queries
|
|
│ │ ├─ links.py # Extract Markdown/[[WikiLinks]]; resolve; backlinks
|
|
│ │ └─ watcher.py # watchdog observers to update index on changes
|
|
│ ├─ utils/
|
|
│ │ ├─ time.py # ISO timestamp helpers
|
|
│ │ ├─ slugs.py # Slugify utilities
|
|
│ │ └─ paths.py # Safe atomic writes, backups, path utils
|
|
│ ├─ templates/
|
|
│ │ ├─ _partials/
|
|
│ │ │ ├─ navbar.html
|
|
│ │ │ ├─ note_meta.html # Tags/status/aliases pills
|
|
│ │ │ └─ search_box.html
|
|
│ │ ├─ base.html # DaisyUI layout; theme switch; CSS/JS includes
|
|
│ │ ├─ home.html # Recent notes; quick search
|
|
│ │ ├─ notes/
|
|
│ │ │ ├─ list.html
|
|
│ │ │ ├─ view.html # Content + backlinks + outbound links
|
|
│ │ │ └─ edit.html # CodeMirror editor + metadata form
|
|
│ │ └─ search/
|
|
│ │ └─ results.html
|
|
│ ├─ static/
|
|
│ │ ├─ css/
|
|
│ │ │ ├─ input.css # @tailwind base; @tailwind components; @tailwind utilities;
|
|
│ │ │ └─ app.css # Built CSS (gitignored if desired)
|
|
│ │ ├─ js/
|
|
│ │ │ ├─ editor.js # CodeMirror 6 init (ESM); drag-drop/paste handler
|
|
│ │ │ └─ app.js # Small client-side helpers (palette, shortcuts)
|
|
│ │ └─ imgs/
|
|
│ │ └─ logo.svg
|
|
│ └─ schema.sql # SQLite schema incl. FTS5 and backlinks tables
|
|
├─ cli.py # CLI entrypoint: `pkm run --vault <path>`
|
|
├─ pyproject.toml # Python project + dependencies (Flask, markdown-it-py, bleach, watchdog, pyyaml)
|
|
├─ requirements.txt # (optional alternative to pyproject)
|
|
├─ tailwind.config.cjs # Tailwind + DaisyUI plugin config
|
|
├─ postcss.config.cjs # (optional, if using PostCSS plugins explicitly)
|
|
├─ package.json # Dev deps: tailwindcss, daisyui; scripts to build/watch CSS
|
|
├─ .gitignore
|
|
├─ .env.example # KB_VAULT_PATH=...
|
|
└─ README.md
|
|
```
|
|
|
|
SQLite schema outline (`app/schema.sql`)
|
|
```sql
|
|
-- Notes catalog (lightweight metadata separate from content)
|
|
CREATE TABLE IF NOT EXISTS notes (
|
|
id TEXT PRIMARY KEY, -- UUID
|
|
path TEXT NOT NULL, -- relative to vault root, e.g., notes/foo/bar.md
|
|
title TEXT NOT NULL,
|
|
created TEXT NOT NULL, -- ISO UTC
|
|
updated TEXT NOT NULL, -- ISO UTC
|
|
tags TEXT, -- JSON-encoded array or comma-separated
|
|
status TEXT,
|
|
aliases TEXT -- JSON-encoded array
|
|
);
|
|
|
|
-- Backlinks (resolved by id)
|
|
CREATE TABLE IF NOT EXISTS links (
|
|
src_id TEXT NOT NULL,
|
|
dst_id TEXT NOT NULL,
|
|
src_anchor TEXT, -- optional: section/heading/context
|
|
PRIMARY KEY (src_id, dst_id)
|
|
);
|
|
|
|
-- FTS5 virtual table for full-text search
|
|
CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts
|
|
USING fts5(
|
|
title, body, tags,
|
|
content='',
|
|
tokenize='porter' -- or unicode61 with custom config
|
|
);
|
|
|
|
-- Content-to-FTS sync tables (manual sync via triggers or code)
|
|
CREATE TABLE IF NOT EXISTS notes_content (
|
|
id TEXT PRIMARY KEY,
|
|
body TEXT NOT NULL
|
|
);
|
|
```
|
|
|
|
Vault layout on disk (user-provided path; created/validated at first run)
|
|
```
|
|
<vault>/
|
|
├─ notes/ # Markdown notes (nested folders allowed)
|
|
├─ attachments/ # Images/PDFs and other assets
|
|
└─ .kb/
|
|
├─ index.sqlite # FTS5 index + backlinks + metadata cache
|
|
├─ config.yml # App config/preferences (optional for v1)
|
|
└─ cache/ # Thumbnails, temp files (optional)
|
|
```
|
|
|
|
Dependencies (initial)
|
|
- Python: Flask, Jinja2, markdown-it-py, bleach, PyYAML (or python-frontmatter), watchdog, click (for CLI).
|
|
- System: SQLite with FTS5 enabled (commonly available).
|
|
- Frontend: Tailwind CSS, DaisyUI (Tailwind plugin), CodeMirror 6 via ESM imports (from CDN) or npm if bundling later.
|
|
|
|
Scripts (suggested)
|
|
- package.json
|
|
- build: `tailwindcss -c tailwind.config.cjs -i ./app/static/css/input.css -o ./app/static/css/app.css --minify`
|
|
- watch: `tailwindcss -c tailwind.config.cjs -i ./app/static/css/input.css -o ./app/static/css/app.css --watch`
|
|
- CLI
|
|
- `python cli.py run --vault /path/to/vault` (wraps Flask app with vault path)
|
|
|
|
Notes
|
|
- Keep server-rendered pages; use minimal JS for editor and quick search.
|
|
- Sanitize rendered HTML; set a Content Security Policy where possible.
|
|
- For Obsidian compatibility, prefer not to modify file structure beyond `.kb` internals. |