# ganiket25201001/hid-v2 architecture

> Architecture diagram of the GitHub repository ganiket25201001/hid-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ganiket25201001/hid-v2
- Repository: https://github.com/ganiket25201001/hid-v2

## Overview

1. **Application shape and runtime**
   HID Shield is a PySide6 desktop security console, not a web service. The app starts from `main.py` and runs as a single local GUI process with a persistence layer backed by SQLite (`hid_shield.db`). Most behavior is event-driven rather than request/response.

2. **Top-level orchestration**
   The repository is organized around a central event bus (`core/event_bus.py`) that decouples device monitoring, analysis, security decisions, and UI updates. This is the main integration boundary: core modules emit events, and UI / policy / storage modules subscribe to them.

3. **Device and OS-facing boundary**
   USB/HID activity is handled in `core/usb_monitor.py`, with supporting device metadata logic in `core/device_info.py` and enforcement-related logic in `core/port_lockdown.py`. This is the OS-adjacent layer where physical device changes enter the system. The README makes clear the app is simulation-first, so real enforcement is intentionally limited unless stronger OS integration/admin privileges are available.

4. **Analysis pipeline**
   Suspicious files or device payloads flow into the sandbox subsystem under `sandbox/`. The pipeline is split into `file_scanner.py`, `entropy_analyzer.py`, `pe_analyzer.py`, and `sandbox_manager.py`, indicating layered inspection: file enumeration, heuristics, entropy-based checks, and executable-specific analysis. This subsystem produces structured findings that feed downstream threat scoring.

5. **Threat classification layer**
   The ML package under `ml/` converts analysis outputs into deterministic threat judgments. `feature_extractor.py` defines the feature contract, while `classifier.py` is the public entry point and `mock_classifier.py` provides the current stable demo backend. Architecturally, this is a swappable inference boundary: the README explicitly notes future replacement with a real model while preserving the same feature vector interface.

6. **Security policy and access control**
   The `security/` package is the decision layer that turns analysis results into allow/block/approve actions. `policy_engine.py` encodes thresholds and rules, `access_controller.py` applies those decisions, `whitelist_manager.py` handles trusted hardware serials, and `auth_manager.py` / `session_manager.py` control operator authentication and session lifetime. This layer sits between detection/analysis and any user-visible or enforcement action.

7. **Persistence and audit trail**
   Database access is isolated under `database/` with `db.py`, `models.py`, and `repository.py`. The likely data model supports event logs, scan results, alerts, sessions, and whitelist records, which are then surfaced in the UI and reports. The presence of SQLite WAL files suggests local audit-grade persistence with concurrent read/write support.

8. **Operator workflow and UI composition**
   The `ui/` package is a multi-screen analyst console: dashboard, USB detection, threat analysis, decision panel, logs, and settings. `main_window.py` is the shell, while `dashboard.py`, `usb_detection.py`, `threat_analysis.py`, `decision_panel.py`, `logs_screen.py`, and `settings_screen.py` are the major views. The UI is built from reusable widgets under `ui/widgets/` for risk gauges, file trees, tables, badges, and animated presentation elements.

9. **Reporting and forensic output**
   `reports/pdf_exporter.py` turns stored incident data into PDF reports. This is a separate output boundary from the live UI, using persisted events and analysis results to generate offline forensic artifacts for review or sharing.

10. **Configuration and runtime controls**
    `config.yaml` is the main operational configuration source, covering policy thresholds, default actions, notification behavior, logging, and session controls. `.env.example` suggests environment-based secrets or local overrides are also supported. The UI settings screen likely edits a subset of these runtime controls.

11. **Static assets and presentation layer**
    Visual styling is centralized in `ui/styles/` with QSS and theme code, while fonts live under `assets/fonts/`. This matters architecturally because the app has a branded analyst-console presentation layer, but these assets do not affect core security flow.

12. **Testing and smoke validation**
    The repository includes UI and monitor test scripts (`test_ui.py`, `test_dashboard.py`, `test_monitor.py`) that appear to exercise the main event flow, UI rendering, and USB-monitor simulation. These are useful for understanding expected subsystem integration: detection → analysis → decision → logging/reporting.

13. **Main end-to-end data flow**
    The primary flow is: USB/HID event enters via the monitor, the event bus distributes it, the sandbox and ML layers generate risk signals, the policy engine and access controller decide what to do, the result is persisted in SQLite, and the UI updates live while also supporting logs and PDF export. Authentication and whitelisting gate operator actions across that flow.

Main entry points: [`ui/main_window.py`](https://github.com/ganiket25201001/hid-v2/blob/main/ui/main_window.py) (Main window), [`core/event_bus.py`](https://github.com/ganiket25201001/hid-v2/blob/main/core/event_bus.py) (Event bus), [`database/repository.py`](https://github.com/ganiket25201001/hid-v2/blob/main/database/repository.py) (Repository), [`sandbox/sandbox_manager.py`](https://github.com/ganiket25201001/hid-v2/blob/main/sandbox/sandbox_manager.py) (Sandbox)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main_py(("App start<br/>entrypoint<br/>[main.py]"))
  node_config_yaml["Config<br/>settings<br/>[config.yaml]"]
end

subgraph group_core["Core"]
  node_event_bus(("Event bus<br/>pubsub<br/>[event_bus.py]"))
  node_usb_monitor["USB monitor<br/>device monitor<br/>[usb_monitor.py]"]
  node_device_info["Device info<br/>device metadata<br/>[device_info.py]"]
  node_port_lockdown["Port lockdown<br/>enforcement<br/>[port_lockdown.py]"]
end

subgraph group_analysis["Analysis"]
  node_sandbox_manager["Sandbox<br/>analysis pipeline<br/>[sandbox_manager.py]"]
  node_file_scanner["File scan<br/>scanner<br/>[file_scanner.py]"]
  node_entropy_analyzer["Entropy<br/>heuristic analyzer"]
  node_pe_analyzer["PE analyzer<br/>binary analyzer<br/>[pe_analyzer.py]"]
  node_feature_extractor["Features<br/>feature contract"]
  node_classifier["Classifier<br/>inference api<br/>[classifier.py]"]
  node_mock_classifier["Mock model<br/>demo backend<br/>[mock_classifier.py]"]
end

subgraph group_security["Security"]
  node_policy_engine["Policy engine<br/>rules engine<br/>[policy_engine.py]"]
  node_access_controller["Access control<br/>decision enforcement"]
  node_whitelist_manager["Whitelist<br/>trust store"]
  node_auth_manager(("Auth<br/>[auth_manager.py]"))
  node_session_manager(("Session<br/>[session_manager.py]"))
end

subgraph group_data["Data"]
  node_db[("SQLite DB<br/>persistence<br/>[db.py]")]
  node_models["Models<br/>schema<br/>[models.py]"]
  node_repository["Repository<br/>data access<br/>[repository.py]"]
end

subgraph group_ui["UI"]
  node_main_window["Main window<br/>ui shell<br/>[main_window.py]"]
  node_dashboard["Dashboard<br/>screen<br/>[dashboard.py]"]
  node_usb_detection["USB view<br/>screen<br/>[usb_detection.py]"]
  node_threat_analysis["Analysis view<br/>screen<br/>[threat_analysis.py]"]
  node_decision_panel["Decision panel<br/>screen<br/>[decision_panel.py]"]
  node_logs_screen["Logs<br/>screen<br/>[logs_screen.py]"]
  node_settings_screen["Settings<br/>screen<br/>[settings_screen.py]"]
  node_widgets["Shared widgets<br/>ui components"]
end

subgraph group_output["Output"]
  node_pdf_exporter["PDF export<br/>reporting<br/>[pdf_exporter.py]"]
end

node_main_py -->|"loads"| node_config_yaml
node_main_py -->|"initializes"| node_event_bus
node_main_py -->|"starts"| node_usb_monitor
node_main_py -->|"opens"| node_main_window
node_usb_monitor -->|"enriches"| node_device_info
node_usb_monitor -->|"publishes"| node_event_bus
node_event_bus -->|"dispatches"| node_sandbox_manager
node_sandbox_manager -->|"runs"| node_file_scanner
node_sandbox_manager -->|"runs"| node_entropy_analyzer
node_sandbox_manager -->|"runs"| node_pe_analyzer
node_sandbox_manager -->|"produces"| node_feature_extractor
node_feature_extractor -->|"feeds"| node_classifier
node_classifier -->|"backs"| node_mock_classifier
node_classifier -->|"scores"| node_policy_engine
node_policy_engine -->|"decides"| node_access_controller
node_whitelist_manager -->|"informs"| node_policy_engine
node_auth_manager -->|"creates"| node_session_manager
node_session_manager -->|"gates"| node_access_controller
node_access_controller -->|"enforces"| node_port_lockdown
node_policy_engine -->|"records"| node_repository
node_event_bus -->|"logs"| node_repository
node_repository -->|"stores"| node_db
node_db -->|"maps"| node_models
node_main_window -->|"hosts"| node_dashboard
node_main_window -->|"hosts"| node_usb_detection
node_main_window -->|"hosts"| node_threat_analysis
node_main_window -->|"hosts"| node_decision_panel
node_main_window -->|"hosts"| node_logs_screen
node_main_window -->|"hosts"| node_settings_screen
node_dashboard -->|"subscribes"| node_event_bus
node_usb_detection -->|"subscribes"| node_event_bus
node_threat_analysis -->|"reads"| node_repository
node_logs_screen -->|"reads"| node_repository
node_decision_panel -->|"drives"| node_access_controller
node_settings_screen -->|"edits"| node_config_yaml
node_pdf_exporter -->|"reads"| node_repository
node_pdf_exporter -->|"exports"| node_db
node_widgets -->|"supports"| node_dashboard
node_widgets -->|"supports"| node_threat_analysis
node_widgets -->|"supports"| node_logs_screen

click node_main_py "https://github.com/ganiket25201001/hid-v2/blob/main/main.py"
click node_config_yaml "https://github.com/ganiket25201001/hid-v2/blob/main/config.yaml"
click node_event_bus "https://github.com/ganiket25201001/hid-v2/blob/main/core/event_bus.py"
click node_usb_monitor "https://github.com/ganiket25201001/hid-v2/blob/main/core/usb_monitor.py"
click node_device_info "https://github.com/ganiket25201001/hid-v2/blob/main/core/device_info.py"
click node_port_lockdown "https://github.com/ganiket25201001/hid-v2/blob/main/core/port_lockdown.py"
click node_sandbox_manager "https://github.com/ganiket25201001/hid-v2/blob/main/sandbox/sandbox_manager.py"
click node_file_scanner "https://github.com/ganiket25201001/hid-v2/blob/main/sandbox/file_scanner.py"
click node_entropy_analyzer "https://github.com/ganiket25201001/hid-v2/blob/main/sandbox/entropy_analyzer.py"
click node_pe_analyzer "https://github.com/ganiket25201001/hid-v2/blob/main/sandbox/pe_analyzer.py"
click node_feature_extractor "https://github.com/ganiket25201001/hid-v2/blob/main/ml/feature_extractor.py"
click node_classifier "https://github.com/ganiket25201001/hid-v2/blob/main/ml/classifier.py"
click node_mock_classifier "https://github.com/ganiket25201001/hid-v2/blob/main/ml/mock_classifier.py"
click node_policy_engine "https://github.com/ganiket25201001/hid-v2/blob/main/security/policy_engine.py"
click node_access_controller "https://github.com/ganiket25201001/hid-v2/blob/main/security/access_controller.py"
click node_whitelist_manager "https://github.com/ganiket25201001/hid-v2/blob/main/security/whitelist_manager.py"
click node_auth_manager "https://github.com/ganiket25201001/hid-v2/blob/main/security/auth_manager.py"
click node_session_manager "https://github.com/ganiket25201001/hid-v2/blob/main/security/session_manager.py"
click node_db "https://github.com/ganiket25201001/hid-v2/blob/main/database/db.py"
click node_models "https://github.com/ganiket25201001/hid-v2/blob/main/database/models.py"
click node_repository "https://github.com/ganiket25201001/hid-v2/blob/main/database/repository.py"
click node_main_window "https://github.com/ganiket25201001/hid-v2/blob/main/ui/main_window.py"
click node_dashboard "https://github.com/ganiket25201001/hid-v2/blob/main/ui/dashboard.py"
click node_usb_detection "https://github.com/ganiket25201001/hid-v2/blob/main/ui/usb_detection.py"
click node_threat_analysis "https://github.com/ganiket25201001/hid-v2/blob/main/ui/threat_analysis.py"
click node_decision_panel "https://github.com/ganiket25201001/hid-v2/blob/main/ui/decision_panel.py"
click node_logs_screen "https://github.com/ganiket25201001/hid-v2/blob/main/ui/logs_screen.py"
click node_settings_screen "https://github.com/ganiket25201001/hid-v2/blob/main/ui/settings_screen.py"
click node_widgets "https://github.com/ganiket25201001/hid-v2/tree/main/ui/widgets"
click node_pdf_exporter "https://github.com/ganiket25201001/hid-v2/blob/main/reports/pdf_exporter.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_py,node_config_yaml,node_pdf_exporter toneBlue
class node_event_bus,node_usb_monitor,node_device_info,node_port_lockdown toneAmber
class node_sandbox_manager,node_file_scanner,node_entropy_analyzer,node_pe_analyzer,node_feature_extractor,node_classifier,node_mock_classifier toneMint
class node_policy_engine,node_access_controller,node_whitelist_manager,node_auth_manager,node_session_manager toneRose
class node_db,node_models,node_repository toneIndigo
class node_main_window,node_dashboard,node_usb_detection,node_threat_analysis,node_decision_panel,node_logs_screen,node_settings_screen,node_widgets toneTeal
```

## Components

### Runtime

Local desktop application entry and configuration

- [App start](https://github.com/ganiket25201001/hid-v2/blob/main/main.py): entrypoint · Bootstraps the desktop console and wires runtime components · `main.py`
- [Config](https://github.com/ganiket25201001/hid-v2/blob/main/config.yaml): settings · Operational thresholds and runtime controls · `config.yaml`

### Core

Event bus and USB/HID boundary

- [Event bus](https://github.com/ganiket25201001/hid-v2/blob/main/core/event_bus.py): pubsub · Central decoupling layer for system events · `core/event_bus.py`
- [USB monitor](https://github.com/ganiket25201001/hid-v2/blob/main/core/usb_monitor.py): device monitor · Detects HID and USB activity entering the system · `core/usb_monitor.py`
- [Device info](https://github.com/ganiket25201001/hid-v2/blob/main/core/device_info.py): device metadata · Normalizes device identity and attributes · `core/device_info.py`
- [Port lockdown](https://github.com/ganiket25201001/hid-v2/blob/main/core/port_lockdown.py): enforcement · OS-adjacent control for restricting ports or devices · `core/port_lockdown.py`

### Analysis

Sandbox and threat scoring pipeline

- [Sandbox](https://github.com/ganiket25201001/hid-v2/blob/main/sandbox/sandbox_manager.py): analysis pipeline · Coordinates file and payload inspection stages · `sandbox/sandbox_manager.py`
- [File scan](https://github.com/ganiket25201001/hid-v2/blob/main/sandbox/file_scanner.py): scanner · Enumerates and inspects candidate files or payloads · `sandbox/file_scanner.py`
- [Entropy](https://github.com/ganiket25201001/hid-v2/blob/main/sandbox/entropy_analyzer.py): heuristic analyzer · Heuristic signal for packed or suspicious content · `sandbox/entropy_analyzer.py`
- [PE analyzer](https://github.com/ganiket25201001/hid-v2/blob/main/sandbox/pe_analyzer.py): binary analyzer · Executable-specific inspection for Windows payloads · `sandbox/pe_analyzer.py`
- [Features](https://github.com/ganiket25201001/hid-v2/blob/main/ml/feature_extractor.py): feature contract · Transforms analysis outputs into model features · `ml/feature_extractor.py`
- [Classifier](https://github.com/ganiket25201001/hid-v2/blob/main/ml/classifier.py): inference api · Public threat scoring entry point · `ml/classifier.py`
- [Mock model](https://github.com/ganiket25201001/hid-v2/blob/main/ml/mock_classifier.py): demo backend · Current stable classifier implementation · `ml/mock_classifier.py`

### Security

Policy, auth, and access control

- [Policy engine](https://github.com/ganiket25201001/hid-v2/blob/main/security/policy_engine.py): rules engine · Converts threat signals into allow or block decisions · `security/policy_engine.py`
- [Access control](https://github.com/ganiket25201001/hid-v2/blob/main/security/access_controller.py): decision enforcement · Applies policy decisions to device or operator actions · `security/access_controller.py`
- [Whitelist](https://github.com/ganiket25201001/hid-v2/blob/main/security/whitelist_manager.py): trust store · Tracks trusted hardware serials and allowed devices · `security/whitelist_manager.py`
- [Auth](https://github.com/ganiket25201001/hid-v2/blob/main/security/auth_manager.py): authentication · Operator authentication boundary · `security/auth_manager.py`
- [Session](https://github.com/ganiket25201001/hid-v2/blob/main/security/session_manager.py): session control · Manages authenticated operator session lifetime · `security/session_manager.py`

### Data

SQLite persistence and audit storage

- [SQLite DB](https://github.com/ganiket25201001/hid-v2/blob/main/database/db.py): persistence · Local audit and state store · `database/db.py`
- [Models](https://github.com/ganiket25201001/hid-v2/blob/main/database/models.py): schema · Database entities for events, scans, alerts, and sessions · `database/models.py`
- [Repository](https://github.com/ganiket25201001/hid-v2/blob/main/database/repository.py): data access · Persistence gateway used by app services · `database/repository.py`

### UI

Operator console and major screens

- [Main window](https://github.com/ganiket25201001/hid-v2/blob/main/ui/main_window.py): ui shell · Desktop application shell that hosts the analyst console · `ui/main_window.py`
- [Dashboard](https://github.com/ganiket25201001/hid-v2/blob/main/ui/dashboard.py): screen · Overview screen for current system and threat status · `ui/dashboard.py`
- [USB view](https://github.com/ganiket25201001/hid-v2/blob/main/ui/usb_detection.py): screen · Live device detection and monitoring screen · `ui/usb_detection.py`
- [Analysis view](https://github.com/ganiket25201001/hid-v2/blob/main/ui/threat_analysis.py): screen · Presents sandbox and classifier results · `ui/threat_analysis.py`
- [Decision panel](https://github.com/ganiket25201001/hid-v2/blob/main/ui/decision_panel.py): screen · Operator controls for allow, block, and approval actions · `ui/decision_panel.py`
- [Logs](https://github.com/ganiket25201001/hid-v2/blob/main/ui/logs_screen.py): screen · Audit trail and event history view · `ui/logs_screen.py`
- [Settings](https://github.com/ganiket25201001/hid-v2/blob/main/ui/settings_screen.py): screen · Runtime and policy configuration UI · `ui/settings_screen.py`
- [Shared widgets](https://github.com/ganiket25201001/hid-v2/tree/main/ui/widgets): ui components · Reusable UI controls for risk, tables, trees, and effects · `ui/widgets`

### Output

Offline reporting and exports

- [PDF export](https://github.com/ganiket25201001/hid-v2/blob/main/reports/pdf_exporter.py): reporting · Generates offline incident reports from persisted data · `reports/pdf_exporter.py`

## Connections

- App start → Config: loads · Reads runtime thresholds and defaults
- App start → Event bus: initializes · Creates the central event coordination layer
- App start → USB monitor: starts · Launches device monitoring in the desktop process
- App start → Main window: opens · Starts the operator console
- USB monitor → Device info: enriches · Attaches device metadata to incoming events
- USB monitor → Event bus: publishes · Emits HID and USB events
- Event bus → Sandbox: dispatches · Routes suspicious payloads to inspection
- Sandbox → File scan: runs · Enumerates files and payloads
- Sandbox → Entropy: runs · Adds heuristic risk signals
- Sandbox → PE analyzer: runs · Performs executable inspection
- Sandbox → Features: produces · Builds model-ready feature vectors
- Features → Classifier: feeds · Supplies normalized features for inference
- Classifier → Mock model: backs · Current backend implementation
- Classifier → Policy engine: scores · Outputs threat judgments used by policy
- Policy engine → Access control: decides · Converts scores into actionable decisions
- Whitelist → Policy engine: informs · Trusted devices reduce or bypass risk
- Auth → Session: creates · Authenticated operators receive sessions
- Session → Access control: gates · Restricts privileged actions to active sessions
- Access control → Port lockdown: enforces · Applies device or port restrictions when possible
- Policy engine → Repository: records · Persists decisions and supporting evidence
- Event bus → Repository: logs · Writes operational events and alerts
- Repository → SQLite DB: stores · Uses local SQLite persistence
- SQLite DB → Models: maps · Backs records with structured entities
- Main window → Dashboard: hosts · Primary overview screen
- Main window → USB view: hosts · Device monitoring screen
- Main window → Analysis view: hosts · Threat inspection screen
- Main window → Decision panel: hosts · Operator action screen
- Main window → Logs: hosts · Audit history screen
- Main window → Settings: hosts · Configuration screen
- Dashboard → Event bus: subscribes · Displays live system state from events
- USB view → Event bus: subscribes · Shows device activity updates
- Analysis view → Repository: reads · Loads scan and score history
- Logs → Repository: reads · Queries audit records
- Decision panel → Access control: drives · Invokes approve or block actions
- Settings → Config: edits · Adjusts runtime policy and UI settings
- PDF export → Repository: reads · Pulls persisted incidents and scans
- PDF export → SQLite DB: exports · Supports offline forensic reporting
- Shared widgets → Dashboard: supports · Shared visual controls used across screens
- Shared widgets → Analysis view: supports · Shared visual controls used across screens
- Shared widgets → Logs: supports · Shared visual controls used across screens
