How mickael-menu/zk works
Project type and purpose
• “zk” is a command-line note-taking assistant written in Go.
• It implements a Hexagonal/Ports & Adapters architecture:
– Core domain logic lives in internal/core.
– Adapters for persistence, templating, UI, and external tools live in internal/adapter.
– The CLI layer in internal/cli wires everything together.
Main components
A. CLI Layer (main.go, internal/cli)
• Parses user commands (init, new, list, edit, graph, lsp, etc.).
• Loads configuration (from .zk/config.toml).
• Instantiates core services and injects concrete adapters.
B. Core Domain (internal/core)
• Models Notes, Collections, Links, Templates.
• Implements business use cases: create, find, format, index notes.
• Exposes interfaces (ports) for persistence and external interactions.
C. Adapters (internal/adapter)
• Filesystem Adapter (fs): reads/writes Markdown files and configs.
• SQLite Adapter (sqlite): persistence via local .zk.db (DAOs).
• Templating Adapter (handlebars): applies Handlebars templates to notes.
• Markdown Adapter (markdown): parses and renders markdown, wikilinks, tags.
• LSP Adapter (lsp): implements Language Server Protocol for editor integration.
• Interactive UI Adapter (fzf): shells out to fzf for note picking.
• Editor Adapter (editor): opens notes in user’s $EDITOR.
D. Utilities (internal/util)
• Logging, path walking, error handling, exec wrappers, FTS5 helper, etc.
E. External Dependencies
• SQLite binary and Go’s database/sql.
• Handlebars Go library.
• fzf executable.
• Any LSP-capable editor.
Relationships and data flow
1. User runs zk <command> → CLI Layer
2. CLI loads config → instantiates Core services + Adapters
3. Core service invokes Adapter ports:
– To read/write files → Filesystem Adapter
– To query or store note metadata → SQLite Adapter
– To render output → Markdown & Handlebars Adapters
– To open an editor → Editor Adapter
– To show interactive lists → fzf Adapter
– To serve LSP → LSP Adapter
4. Adapters call external systems (file system, subprocesses, DB).
Architectural patterns & principles
• Hexagonal (Ports & Adapters) keeps Core independent of tooling.
• Single Responsibility: each adapter focuses on one external system.
• Dependency Injection: CLI wires adapters into core interfaces.
• Layered approach: CLI → Core → Adapters → External Systems.