AWatch-rus/docs/architecture-diagram.md

ActivityWatch-Russian Architecture Diagram

High-Level Architecture

graph TB
    subgraph "Windows Clients"
        A[ActivityWatch Watchers]
        B[DLP Endpoint Collector]
        C[Browser Domains Collector]
        D[Email Outbound Collector]
        E[Worktime Session Collector]
    end

    subgraph "Linux Server"
        F[ActivityWatch Server]
        G[PostgreSQL Database]
        H[Aggregation Scripts]
    end

    subgraph "Monitoring & Integration"
        I[pfSense Firewall]
        J[Prometheus Exporter]
    end

    subgraph "Visualization"
        K[Grafana]
        L[Prometheus]
        M[ActivityWatch WebUI]
    end

    A -->|HTTP API| F
    B -->|Events| F
    C -->|Events| F
    D -->|Events| F
    E -->|Events| F
    
    F -->|Store| G
    F -->|API| M
    
    I -->|Logs| F
    H -->|Read/Write| G
    H -->|Read| F
    
    J -->|Metrics| L
    L -->|Scrape| J
    F -->|API| J
    
    K -->|Query| L
    K -->|Query| G

Component Interactions

Data Flow

Windows Collectors → ActivityWatch Server → PostgreSQL Database
                                    ↓
                            Aggregation Scripts
                                    ↓
                            Grafana Dashboards

DLP Monitoring Flow

User Activity (clipboard/print/USB) 
    ↓
DLP Endpoint Collector (PowerShell)
    ↓
DLP Policy Evaluation
    ↓
ActivityWatch Events (via HTTP API)
    ↓
PostgreSQL Database
    ↓
Aggregation Scripts (Python)
    ↓
Grafana DLP Dashboard

Browser Monitoring Flow

User Browser Activity
    ↓
Browser Domains Collector (PowerShell)
    ↓
Domain Extraction & Categorization
    ↓
DLP Rule Check
    ↓
ActivityWatch Events
    ↓
WebUI Domain Dashboard

Email Monitoring Flow

Outlook / SMTP Activity
    ↓
Email Outbound Collector (PowerShell)
    ↓
Email Policy Evaluation
    ↓
ActivityWatch Events
    ↓
Grafana Email Dashboard

pfSense Integration Flow

pfSense Firewall Logs
    ↓
pfSense Poller (Python)
    ↓
HTTP API Query
    ↓
ActivityWatch Events
    ↓
Network Activity Dashboard

Metrics Flow

ActivityWatch Server
    ↓
Prometheus Exporter (Python)
    ↓
HTTP Metrics Endpoint (port 9398)
    ↓
Prometheus Scraping
    ↓
Grafana Dashboards

Component Details

Windows Collectors

Component	Language	Purpose	Output
DLP Endpoint Collector	PowerShell	Monitor clipboard, print, USB	ActivityWatch events
Browser Domains Collector	PowerShell	Track visited domains	ActivityWatch events
Email Outbound Collector	PowerShell	Monitor sent emails	ActivityWatch events
Worktime Session Collector	PowerShell	Track work sessions	ActivityWatch events

Server Components

Component	Language	Purpose	Dependencies
ActivityWatch Server	Rust	Core monitoring platform	SQLite/PostgreSQL
Aggregation Scripts	Python	Process DLP events	psycopg2, requests
Prometheus Exporter	Python	Export metrics to Prometheus	prometheus_client

Integration Points

Integration	Protocol	Purpose
pfSense → AW	HTTP API	Firewall log collection
AW → Grafana	PostgreSQL	Direct database access
AW → Prometheus	HTTP /metrics	Metrics scraping
Collectors → AW	HTTP /api/buckets	Event submission

Deployment Architecture

Domain Controller
    ↓ (GPO / Scheduled Tasks)
Windows Workstations (user1, user2, ...)
    ↓ (PowerShell Collectors)
ActivityWatch Server (Linux)
    ↓
PostgreSQL Database
    ↓
Grafana + Prometheus Stack

File System Structure

ActivityWatch-Russian/
├── windows/                          # Windows collectors
│   ├── dlp-endpoint-signals-collector.ps1
│   ├── browser-domains-native-collector.ps1
│   ├── email-outbound-collector.ps1
│   ├── worktime-session-collector.ps1
│   ├── deploy-domain-users.ps1      # Deployment script
│   └── ActivityWatch.Windows.Common.psm1
├── scripts/                          # Server scripts
│   ├── aggregate_dlp_events.py
│   └── merge_aw_server_dbs.py
├── aw-server/                        # WebUI patches
│   ├── aw-ru-patch.js
│   └── aw-sw-cleanup.js
├── pfsense/                          # pfSense integration
│   └── pfsense-aw-poller.py
├── grafana-1c/                       # Monitoring stack
│   ├── docker-compose.yml
│   ├── prometheus/
│   ├── grafana/
│   └── sql-exporter/
│       └── collectors/
│           └── aw_activitywatch.py
└── ansible/                          # Automation
    ├── playbooks/
    └── group_vars/

Network Ports

Service	Port	Protocol	Purpose
ActivityWatch Server	5600	HTTP	WebUI & API
ActivityWatch Server	5666	HTTP	WebSocket
Prometheus	9090	HTTP	Metrics UI
Prometheus Exporter	9398	HTTP	AW metrics endpoint
Grafana	3000	HTTP	Dashboards
PostgreSQL	5432	TCP	Database

Data Models

ActivityWatch Event Structure

{
  "timestamp": "2024-01-01T12:00:00Z",
  "duration": 60.0,
  "data": {
    "title": "Window Title",
    "url": "https://example.com",
    "app": "chrome.exe",
    "type": "activity"
  }
}

DLP Incident Structure

{
  "timestamp": "2024-01-01T12:00:00Z",
  "type": "clipboard",
  "rule": "credit_card_pattern",
  "severity": "high",
  "user": "user1",
  "host": "WORKSTATION01",
  "screenshot": "path/to/screenshot.png"
}

Key Dependencies

Windows Dependencies

• PowerShell 5.1+
• .NET Framework 4.8
• ActivityWatch Windows binaries

Linux Dependencies

• Python 3.8+
• PostgreSQL 12+
• Docker & Docker Compose
• Rust (for AW server compilation)

Python Dependencies

psycopg2-binary
requests
prometheus_client

Security Considerations

Data Flow Security

• Collectors → Server: HTTP (can be upgraded to HTTPS)
• Server → Database: Local connection or SSL
• pfSense → Server: HTTP over VPN
• Prometheus → Exporter: HTTP internal network

Access Control

• Windows collectors run as user context
• Server runs as dedicated service user
• Database access restricted to specific users
• Grafana authenticated via LDAP/Local users

Monitoring & Alerting

Metrics Collected

• Events per bucket
• Active hosts count
• Collector heartbeat status
• DLP incident rate
• Database query performance

Alerting Rules

• Collector offline > 30 minutes
• High DLP incident rate
• Database connection failures
• Disk space < 20%