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)

-- 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.

5.5 KiB Raw Blame History

Initial Directory Structure

5.5 KiB

Raw Blame History