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>
This commit is contained in:
igor04091968
co-authored by
Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
parent
3f3e3a953f
commit
f6074facf5
@@ -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
|
||||
Reference in New Issue
Block a user