verstak/docs/02_Architecture.md

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

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

```text
                 ┌────────────────────┐
                 │     GUI/Wails v2    │
                 └─────────┬──────────┘
                           │
                     ┌───────▼────────┐    ┌─────────────┐
                     │  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 нужен не как главный интерфейс, а как служебный вход.

Команды:

```bash
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. Структура репозитория

```text
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/
      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

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

Типы:

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

Правильно:

```text
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](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.