From f6074facf58d17a0adc6c61b468c262caaa9e981 Mon Sep 17 00:00:00 2001 From: igor04091968 Date: Tue, 5 May 2026 01:45:32 +0300 Subject: [PATCH] docs(graphify): add detailed knowledge graph documentation for wiki - Explain what knowledge graph is and why it's useful - Document all 27 communities with purposes - Describe key components: DLP monitoring, WebUI patches, collectors - Provide usage guide for interactive visualization - Include statistics and architecture recommendations Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- docs/graphify-knowledge-graph.md | 256 +++++++++++++++++++++++++++++++ 1 file changed, 256 insertions(+) create mode 100644 docs/graphify-knowledge-graph.md diff --git a/docs/graphify-knowledge-graph.md b/docs/graphify-knowledge-graph.md new file mode 100644 index 0000000..435dbcf --- /dev/null +++ b/docs/graphify-knowledge-graph.md @@ -0,0 +1,256 @@ +# ActivityWatch-Russian: Knowledge Graph Documentation + +## Что такое Knowledge Graph? + +**Knowledge Graph** (граф знаний) - это визуальное представление связей между компонентами программного проекта. Для ActivityWatch-Russian граф показывает: + +- **Функции и модули** как узлы (nodes) +- **Вызовы и зависимости** как связи (edges) +- **Кластеры** как сообщества связанных функций (communities) + +## Зачем это нужно? + +1. **Понимание архитектуры** - увидеть структуру проекта без чтения кода +2. **Поиск зависимостей** - понять, какие компоненты влияют друг на друга +3. **Выявление изоляции** - найти функции, которые не связаны с остальным кодом +4. **Документация** - автоматическая генерация обзора системы + +## Как был построен граф? + +Граф построен с помощью инструмента **graphify** методом **AST extraction**: + +1. **Сканирование файлов** - найдено 29 кодовых файлов (PowerShell, Python, JavaScript) +2. **Анализ синтаксиса** - извлечены функции, классы, вызовы +3. **Построение графа** - 404 узла (функции), 933 связи (вызовы) +4. **Кластеризация** - 27 сообществ по схожести связей + +## Структура проекта по сообществам + +### 1. DLP Endpoint Monitoring (62 nodes) +**Мониторинг конечных точек DLP** + +Функции для отслеживания: +- **Clipboard** - буфер обмена +- **Print** - задания на печать +- **USB** - запись на USB накопители + +Ключевые файлы: +- `windows/dlp-endpoint-signals-collector.ps1` +- `windows/dlp-policy-test.json` + +### 2. WebUI Russian Localization & Patches (56 nodes) +**Русификация веб-интерфейса** + +Патчи для ActivityWatch WebUI: +- Перевод интерфейса на русский язык +- Скрытие лишних элементов навигации +- Инъекция стилей для RU локали +- Поддержка кириллицы + +Ключевые файлы: +- `aw-server/aw-ru-patch.js` +- `aw-server/aw-sw-cleanup.js` + +### 3. Browser Domains Monitoring (54 nodes) +**Мониторинг доменов браузеров** + +Отслеживание посещаемых сайтов: +- Определение домена из URL +- Категоризация веб-ресурсов +- Проверка DLP правил для доменов +- Скриншоты при нарушениях + +Ключевые файлы: +- `windows/browser-domains-native-collector.ps1` + +### 4. DLP Events Aggregation (38 nodes) +**Агрегация событий DLP** + +Сбор и обработка инцидентов: +- Чтение событий из ActivityWatch buckets +- Нормализация данных +- Запись в PostgreSQL +- Генерация отчетов + +Ключевые файлы: +- `scripts/aggregate_dlp_events.py` + +### 5. DLP Review Center (34 nodes) +**Центр просмотра инцидентов DLP** + +WebUI компоненты для: +- Просмотра списка инцидентов +- Управления правилами DLP +- Архивирования событий +- Фильтрации по хостам + +### 6. Email Outbound Monitoring (34 nodes) +**Мониторинг исходящей почты** + +Отслеживание email: +- Outlook Sent Items +- SMTP соединения +- Проверка DLP правил для email +- Блокировка нарушений + +Ключевые файлы: +- `windows/email-outbound-collector.ps1` + +### 7. Prometheus Metrics Exporter (12 nodes) +**Экспорт метрик для Prometheus** + +Сбор метрик ActivityWatch: +- Количество событий по buckets +- Активность хостов +- Статистика collectors +- HTTP endpoint для Prometheus + +Ключевые файлы: +- `grafana-1c/sql-exporter/collectors/aw_activitywatch.py` + +### 8. pfSense Firewall Integration (12 nodes) +**Интеграция с pfSense** + +Сбор данных с firewall: +- HTTP API опрос +- Парсинг логов pfSense +- Нормализация данных +- Отправка в ActivityWatch + +Ключевые файлы: +- `pfsense/pfsense-aw-poller.py` + +### 9. Migration Scripts (14 nodes) +**Скрипты миграции** + +Обновление путей и конфигураций: +- Перенос данных между версиями +- Обновление конфигурационных файлов +- Конвертация путей + +Ключевые файлы: +- `windows/migrate-awatch-rus-paths.ps1` + +### 10. Worktime Session Tracking (10 nodes) +**Отслеживание рабочих сессий** + +Учет рабочего времени: +- Определение начала/конца сессии +- Учет перерывов +- Агрегация по дням + +Ключевые файлы: +- `windows/worktime-session-collector.ps1` + +### 11. Deployment Automation (6 nodes) +**Автоматизация развертывания** + +Скрипты деплоя: +- `windows/deploy-domain-users.ps1` - доменная развертка +- `windows/deploy-single-user.ps1` - одиночный пользователь +- `windows/deploy-ensemble.ps1` - групповое развертывание + +## Как пользоваться графом? + +### Интерактивная визуализация +Откройте файл `graphify-out/index.html` в браузере: + +- **Zoom** - колесо мыши +- **Pan** - перетаскивание +- **Click node** - детали узла +- **Search** - поиск по названию функции + +### Фильтрация по сообществам +Каждое сообщество имеет свой цвет: +- Синий - DLP мониторинг +- Зеленый - WebUI патчи +- Красный - Collectors +- Желтый - Утилиты + +### Поиск зависимостей +1. Найдите функцию в графе +2. Посмотрите на исходящие связи (что вызывает) +3. Посмотрите на входящие связи (кто вызывает) + +## Интерпретация связей + +### Высокая связность (hub nodes) +Функции с большим количеством связей: +- `*_get_deploymentconfig` - чтение конфигурации +- `*_invoke_awjsonpost` - отправка данных в ActivityWatch +- `*_ensure_bucket` - создание bucket + +### Изолированные компоненты +Маленькие сообщества (1-3 nodes) могут быть: +- Утилитными функциями +- Зависимостями от внешних библиотек +- Устаревшим кодом + +## Статистика проекта + +| Метрика | Значение | +|---------|----------| +| Всего файлов | 29 кодовых файлов | +| Всего функций | 404 | +| Всего связей | 933 | +| Сообществ | 27 | +| Средний размер сообщества | 15 nodes | +| Самое большое сообщество | 62 nodes (DLP Endpoint) | + +## Технологии по типам файлов + +- **PowerShell (.ps1)** - Windows collectors, deployment +- **Python (.py)** - aggregation, exporters, pfSense integration +- **JavaScript (.js)** - WebUI patches +- **JSON** - конфигурации, policies + +## Рекомендации по архитектуре + +### Сильные стороны +1. **Четкая модульность** - каждый collector в своем сообществе +2. **Изоляция DLP** - отдельные компоненты для разных типов мониторинга +3. **Унификация** - общие паттерны в collector'ах + +### Возможные улучшения +1. **Дублирование** - несколько сообществ с похожими функциями (WebUI patches) +2. **Интеграция** - слабые связи между некоторыми компонентами +3. **Документация** - не все функции имеют явные назначения + +## Обновление графа + +Для пересборки графа после изменений кода: + +```bash +cd /mnt/usb_hdd2/Projects/ActivityWatch-Russian +graphify . +``` + +Для инкрементального обновления (только измененные файлы): + +```bash +graphify . --update +``` + +## Полезные запросы + +### Найти путь между функциями +```bash +graphify path "dlp_endpoint_signals_collector_get_deploymentconfig" "aggregate_dlp_events_main" +``` + +### Объяснить функцию +```bash +graphify explain "browser_domains_native_collector_get_hostfromurl" +``` + +### Поиск по вопросу +```bash +graphify query "Как работает мониторинг clipboard?" +``` + +## Ссылки + +- **Интерактивный граф**: `graphify-out/index.html` +- **Отчет**: `graphify-out/GRAPH_REPORT.md` +- **JSON граф**: `graphify-out/graph.json` +- **Graphify документация**: https://github.com/brevity-x/graphify