verstak/docs/02_Architecture.md

Верстак — архитектура

1. Архитектурная схема

                 ┌────────────────────┐
                 │      GUI/Wails      │
                 └─────────┬──────────┘
                           │
┌─────────────┐    ┌───────▼────────┐    ┌─────────────┐
│ TUI/Bubble  │───▶│  Core Library   │◀───│ CLI Commands │
└─────────────┘    └───────┬────────┘    └─────────────┘
                           │
                 ┌─────────▼──────────┐
                 │ Local Vault+SQLite │
                 └─────────┬──────────┘
                           │
                 ┌─────────▼──────────┐
                 │ Sync Client        │
                 └─────────┬──────────┘
                           │
                 ┌─────────▼──────────┐
                 │ Sync Server        │
                 └────────────────────┘

2. Компоненты

Core Library

Общее ядро, которое не зависит от GUI/TUI.

Отвечает за:

• nodes tree;
• vault;
• notes;
• files;
• documents;
• actions;
• worklog;
• activity;
• search;
• import;
• sync client;
• security;
• config.

GUI

Основной интерфейс.

Рекомендуемый стек:

• Go backend;
• Wails;
• Svelte или Vue;
• TypeScript;
• CSS без перегруза.

Функции GUI:

• дерево дел;
• экран “Сегодня”;
• карточка дела;
• Markdown editor;
• файловый список;
• actions buttons;
• worklog;
• поиск;
• sync status;
• импорт DokuWiki;
• разбор конфликтов.

TUI

Быстрый интерфейс из терминала.

Рекомендуемый стек:

• Bubble Tea;
• Bubbles;
• Lip Gloss.

TUI не обязан повторять весь GUI.

Функции:

• найти дело;
• открыть заметку;
• добавить worklog;
• запустить action;
• запустить sync;
• посмотреть “Сегодня”.

CLI

CLI нужен не как главный интерфейс, а как служебный вход.

Команды:

verstak init --vault ~/VerstakVault
verstak sync
verstak index rebuild
verstak import-dokuwiki --pages /path/data/pages
verstak log "Клиенты/Ромашка" --time 3h --text "Обновил витрину"
verstak open "Личные проекты/sshkeeper"
verstak vault check

CLI нужен для:

• автоматизации;
• интеграции с sshkeeper;
• shell scripts;
• импорта;
• восстановления;
• диагностики;
• rescue mode.

Sync Server

Отдельный Go HTTP server.

Функции:

• API key auth;
• push/pull operations;
• upload/download blobs;
• restore manifest;
• snapshots;
• retention deleted files.

3. Структура репозитория

verstak/
  go.mod
  README.md

  cmd/
    verstak/
      main.go
    verstak-gui/
      main.go
    verstak-tui/
      main.go
    verstak-server/
      main.go

  internal/
    core/
      nodes/
      vault/
      storage/
      notes/
      files/
      actions/
      worklog/
      activity/
      search/
      importers/
      sync/
      security/
      config/

    gui/
    tui/
    server/

  frontend/
    src/
      App.svelte
      components/
      routes/
      stores/

  migrations/
    001_init.sql
    002_fts.sql
    003_sync.sql

4. Core modules

nodes

Универсальное дерево.

Типы:

space
case
folder
note
document
file
action
recipe
secret
worklog
link

vault

Работа с локальной папкой:

• init;
• safe paths;
• copy/move/link files;
• trash;
• history;
• integrity check.

storage

SQLite:

• migrations;
• repositories;
• transactions;
• FTS;
• backup db.

notes

Markdown notes:

• create;
• read;
• save;
• version backup;
• import from DokuWiki.

files

• add file;
• link external file;
• open system app;
• detect changes;
• hash;
• MIME;
• missing files.

actions

• open_url;
• open_file;
• open_folder;
• run_command;
• run_script;
• open_terminal;
• launch_app;
• sshkeeper_profile.

worklog

• manual entries;
• approximate time;
• billable flag;
• report generation.

activity

• events;
• suggestions;
• grouping;
• confidence.

search

• SQLite FTS5;
• index notes, files, worklog, actions.

importers

• DokuWiki;
• work folder;
• plain folder;
• maybe Obsidian later.

sync

• device id;
• operations log;
• push/pull;
• blobs;
• conflicts;
• restore.

5. File watching

Не строить систему только на watcher.

Правильно:

snapshot scanner — источник правды
fsnotify watcher — ускоритель
manual scan — fallback

Scanner сравнивает реальность с SQLite:

• new file;
• changed file;
• missing file;
• moved file later;
• hash mismatch.

6. Плагины (Extensibility)

Верстак изначально проектируется как база с плагинами. Базовая модель (дело + заметка + файл + действие + журнал) универсальна. Плагины добавляют функционал без перекомпиляции.

Примеры плагинов:

• calendar — календарь событий с привязкой к делам
• kanban — доска задач внутри дела
• importer-dokuwiki — импорт из DokuWiki
• importer-obsidian — импорт из Obsidian
• browser-activity — отслеживание браузерной активности
• secret-notes — зашифрованные заметки
• client-template — шаблон "Клиент" с полями (сайт, домен, ...)

Архитектура плагинов: docs/09_Extensibility.md

Внешние приложения

Верстак не пишет свой офисный пакет.

MVP:

• Markdown/txt/sh/sql/json/yml — встроенный редактор;
• docx/xlsx/odt/pdf/images — открыть системным приложением;
• после закрытия/сохранения watcher/scanner видит изменение.

7. Безопасность запуска actions

Правила:

• dangerous action требует confirm;
• команды запускать через exec.Command, не через shell, если shell не нужен;
• показывать command, args, working_dir;
• логировать запуск;
• не подставлять пользовательский ввод без escaping;
• не хранить секреты в action logs.