# mickael-menu/zk architecture

> Architecture diagram of the GitHub repository mickael-menu/zk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mickael-menu/zk
- Repository: https://github.com/mickael-menu/zk

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI_main["main.go"]:::cli
        CLI_cli["internal/cli"]:::cli
    end

    %% Core Domain
    subgraph "Core Domain"
        direction TB
        CoreDomain["internal/core"]:::core
    end

    %% Adapters
    subgraph "Adapters"
        direction TB
        FS["Filesystem Adapter\n(fs)"]:::adapter
        SQLite["SQLite Adapter\n(sqlite)"]:::adapter
        Handlebars["Templating Adapter\n(handlebars)"]:::adapter
        Markdown["Markdown Adapter\n(markdown)"]:::adapter
        LSP["LSP Adapter\n(lsp)"]:::adapter
        FZF["Interactive UI Adapter\n(fzf)"]:::adapter
        Editor["Editor Adapter\n(editor)"]:::adapter
        Term["Terminal Adapter\n(term)"]:::adapter
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        FSys["File System"]:::external
        DB["SQLite DB"]:::external
        EditorApp["$EDITOR"]:::external
        FZFExe["fzf executable"]:::external
        LSPClient["LSP-capable Editor"]:::external
    end

    %% Connections
    CLI_main -->|"parses commands\nloads config\nwires adapters"| CoreDomain
    CLI_cli -->|"invokes use cases"| CoreDomain

    CoreDomain -->|"NoteRepository\nFile operations"| FS
    CoreDomain -->|"NoteRepository\nDB operations"| SQLite
    CoreDomain -->|"TemplateRenderer"| Handlebars
    CoreDomain -->|"MarkdownProcessor"| Markdown
    CoreDomain -->|"OpenEditor"| Editor
    CoreDomain -->|"InteractivePicker"| FZF
    CoreDomain -->|"ServeLSP"| LSP
    CoreDomain -->|"StyledOutput"| Term

    FS -->|"read/write files"| FSys
    SQLite -->|"SQL queries"| DB
    Editor -->|"launch editor process"| EditorApp
    FZF -->|"spawn fzf"| FZFExe
    LSP -->|"LSP protocol"| LSPClient

    %% Click Events
    click CLI_main "https://github.com/mickael-menu/zk/blob/main/main.go"
    click CLI_cli "https://github.com/mickael-menu/zk/tree/main/internal/cli"
    click CoreDomain "https://github.com/mickael-menu/zk/tree/main/internal/core"
    click FS "https://github.com/mickael-menu/zk/blob/main/internal/adapter/fs/fs.go"
    click SQLite "https://github.com/mickael-menu/zk/blob/main/internal/adapter/sqlite/db.go"
    click Handlebars "https://github.com/mickael-menu/zk/blob/main/internal/adapter/handlebars/handlebars.go"
    click Markdown "https://github.com/mickael-menu/zk/blob/main/internal/adapter/markdown/markdown.go"
    click LSP "https://github.com/mickael-menu/zk/blob/main/internal/adapter/lsp/server.go"
    click FZF "https://github.com/mickael-menu/zk/blob/main/internal/adapter/fzf/fzf.go"
    click Editor "https://github.com/mickael-menu/zk/blob/main/internal/adapter/editor/editor.go"
    click Term "https://github.com/mickael-menu/zk/blob/main/internal/adapter/term/term.go"

    %% Styles
    classDef cli fill:#CCE5FF,stroke:#3399FF,color:#000;
    classDef core fill:#DFF0D8,stroke:#33CC33,color:#000;
    classDef adapter fill:#FFE5CC,stroke:#FF9933,color:#000;
    classDef external fill:#E0E0E0,stroke:#A0A0A0,color:#000;
```
