AWatch-rus/docs/graphify-knowledge-graph.md

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. Документация - не все функции имеют явные назначения

Обновление графа

Для пересборки графа после изменений кода:

cd <PROJECT_ROOT>
graphify .

Для инкрементального обновления (только измененные файлы):

graphify . --update

Полезные запросы

Найти путь между функциями

graphify path "dlp_endpoint_signals_collector_get_deploymentconfig" "aggregate_dlp_events_main"

Объяснить функцию

graphify explain "browser_domains_native_collector_get_hostfromurl"

Поиск по вопросу

graphify query "Как работает мониторинг clipboard?"

Ссылки

• Интерактивный граф: graphify-out/index.html
• Отчет: graphify-out/GRAPH_REPORT.md
• JSON граф: graphify-out/graph.json
• Graphify документация: https://github.com/brevity-x/graphify