Initial commit.
This commit is contained in:
125
docs/STRUCTURE.md
Normal file
125
docs/STRUCTURE.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user