# shraman-c/watcher architecture

> Architecture diagram of the GitHub repository shraman-c/watcher, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shraman-c/watcher
- Repository: https://github.com/shraman-c/watcher

## Overview

Watcher 2.0 is a Windows desktop file organizer. Users configure watched folders and rules in the React UI; the WebView2 bridge sends those requests to the .NET host, which monitors folders, applies safe organization rules, moves files, and records activity for dashboards, analytics, and undo. The graph preserves the documented shell integrations and migration capability. Some backend wiring and UI pages were not sampled, so those links rely on README statements or are omitted where no relationship is evidenced.

Main entry points: [`src/desktop/Watcher.Desktop/Services/BridgeService.cs`](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Desktop/Services/BridgeService.cs) (Bridge Service), [`src/desktop/Watcher.Core/Organization/FileOrganizationService.cs`](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Organization/FileOrganizationService.cs) (File Organization), [`src/desktop/Watcher.Desktop/MainForm.cs`](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Desktop/MainForm.cs) (Desktop Host), [`src/desktop/Watcher.Core/Monitoring/MonitoringManager.cs`](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Monitoring/MonitoringManager.cs) (Folder Monitoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop UI and Bridge"]
  node_frontend["React Application<br/>[App.tsx]"]
  node_ui_pages["Product Views"]
  node_stores["UI State Stores"]
  node_bridge_client["Bridge Client<br/>[bridgeClient.ts]"]
  node_contracts["Bridge Contracts<br/>[contracts.ts]"]
  node_desktop_host["Desktop Host<br/>[MainForm.cs]"]
  node_bridge_service["Bridge Service<br/>[BridgeService.cs]"]
end

subgraph group_domain["Monitoring and Organization"]
  node_monitor["Folder Monitoring"]
  node_folder_monitor["Folder Watcher<br/>[FolderMonitor.cs]"]
  node_organization["File Organization"]
  node_readiness["Readiness Detection"]
  node_collision["Collision Handling"]
  node_loop_guard["Loop Guard"]
  node_rules["Rule Engine<br/>[RuleEngine.cs]"]
  node_defaults["Default Categories"]
end

subgraph group_data["Persistence and Migration"]
  node_db[("SQLite Database<br/>[DatabaseContext.cs]")]
  node_repositories["Repositories<br/>[Repositories]"]
  node_migration["Legacy Config Migration"]
  node_activity["Activity History"]
end

subgraph group_shell["Windows Integration"]
  node_windows_services["Windows Services<br/>[Windows]"]
end

node_user(("User"))

node_user -->|"uses"| node_frontend
node_frontend -->|"renders"| node_ui_pages
node_frontend -->|"loads state"| node_stores
node_ui_pages -->|"requests data"| node_stores
node_stores -->|"calls actions"| node_bridge_client
node_bridge_client -->|"uses types"| node_contracts
node_bridge_client -->|"sends RPC"| node_bridge_service
node_bridge_service -->|"posts messages"| node_desktop_host
node_desktop_host -->|"starts monitoring"| node_monitor
node_desktop_host -->|"hosts bridge"| node_bridge_service
node_monitor -->|"loads folders"| node_repositories
node_monitor -->|"starts watchers"| node_folder_monitor
node_monitor -->|"organizes existing files"| node_organization
node_organization -->|"evaluates files"| node_rules
node_organization -->|"checks readiness"| node_readiness
node_organization -->|"resolves conflicts"| node_collision
node_organization -->|"checks paths"| node_loop_guard
node_rules -->|"loads defaults"| node_defaults
node_repositories -->|"reads and writes"| node_db
node_bridge_service -->|"serves settings and rules"| node_repositories
node_bridge_service -->|"serves activity"| node_activity
node_activity -->|"persists movements"| node_db
node_migration -->|"migrates configuration"| node_db
node_desktop_host -->|"runs migration"| node_migration
node_bridge_service -->|"uses shell features"| node_windows_services
node_windows_services -->|"notifies and launches"| node_user

click node_frontend "https://github.com/shraman-c/watcher/blob/main/src/frontend/src/App.tsx"
click node_ui_pages "https://github.com/shraman-c/watcher/tree/main/src/frontend/src/pages"
click node_stores "https://github.com/shraman-c/watcher/blob/main/src/frontend/src/stores/useMonitoringStore.ts"
click node_bridge_client "https://github.com/shraman-c/watcher/blob/main/src/frontend/src/services/bridgeClient.ts"
click node_contracts "https://github.com/shraman-c/watcher/blob/main/src/shared/contracts/contracts.ts"
click node_desktop_host "https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Desktop/MainForm.cs"
click node_bridge_service "https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Desktop/Services/BridgeService.cs"
click node_monitor "https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Monitoring/MonitoringManager.cs"
click node_folder_monitor "https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Monitoring/FolderMonitor.cs"
click node_organization "https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Organization/FileOrganizationService.cs"
click node_readiness "https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Organization/FileReadinessDetector.cs"
click node_collision "https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Organization/FileCollisionResolver.cs"
click node_loop_guard "https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Organization/InfiniteLoopGuard.cs"
click node_rules "https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Rules/RuleEngine.cs"
click node_defaults "https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Rules/DefaultCategories.cs"
click node_db "https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Infrastructure/Database/DatabaseContext.cs"
click node_repositories "https://github.com/shraman-c/watcher/tree/main/src/desktop/Watcher.Infrastructure/Repositories"
click node_migration "https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Infrastructure/Configuration/LegacyConfigMigrator.cs"
click node_windows_services "https://github.com/shraman-c/watcher/tree/main/src/desktop/Watcher.Infrastructure/Windows"
click node_activity "https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Infrastructure/Repositories/ActivityRepository.cs"

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_frontend,node_ui_pages,node_stores,node_bridge_client,node_contracts,node_desktop_host,node_bridge_service,node_user toneBlue
class node_monitor,node_folder_monitor,node_organization,node_readiness,node_collision,node_loop_guard,node_rules,node_defaults toneAmber
class node_db,node_repositories,node_migration,node_activity toneMint
class node_windows_services toneRose
```

## Components

### Desktop UI and Bridge

- [React Application](https://github.com/shraman-c/watcher/blob/main/src/frontend/src/App.tsx): `src/frontend/src/App.tsx`
- [Product Views](https://github.com/shraman-c/watcher/tree/main/src/frontend/src/pages): `src/frontend/src/pages`
- [UI State Stores](https://github.com/shraman-c/watcher/blob/main/src/frontend/src/stores/useMonitoringStore.ts): `src/frontend/src/stores/useMonitoringStore.ts`
- [Bridge Client](https://github.com/shraman-c/watcher/blob/main/src/frontend/src/services/bridgeClient.ts): `src/frontend/src/services/bridgeClient.ts`
- [Bridge Contracts](https://github.com/shraman-c/watcher/blob/main/src/shared/contracts/contracts.ts): `src/shared/contracts/contracts.ts`
- [Desktop Host](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Desktop/MainForm.cs): `src/desktop/Watcher.Desktop/MainForm.cs`
- [Bridge Service](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Desktop/Services/BridgeService.cs): `src/desktop/Watcher.Desktop/Services/BridgeService.cs`

### Monitoring and Organization

- [Folder Monitoring](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Monitoring/MonitoringManager.cs): `src/desktop/Watcher.Core/Monitoring/MonitoringManager.cs`
- [Folder Watcher](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Monitoring/FolderMonitor.cs): `src/desktop/Watcher.Core/Monitoring/FolderMonitor.cs`
- [File Organization](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Organization/FileOrganizationService.cs): `src/desktop/Watcher.Core/Organization/FileOrganizationService.cs`
- [Readiness Detection](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Organization/FileReadinessDetector.cs): `src/desktop/Watcher.Core/Organization/FileReadinessDetector.cs`
- [Collision Handling](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Organization/FileCollisionResolver.cs): `src/desktop/Watcher.Core/Organization/FileCollisionResolver.cs`
- [Loop Guard](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Organization/InfiniteLoopGuard.cs): `src/desktop/Watcher.Core/Organization/InfiniteLoopGuard.cs`
- [Rule Engine](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Rules/RuleEngine.cs): `src/desktop/Watcher.Core/Rules/RuleEngine.cs`
- [Default Categories](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Core/Rules/DefaultCategories.cs): `src/desktop/Watcher.Core/Rules/DefaultCategories.cs`

### Persistence and Migration

- [SQLite Database](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Infrastructure/Database/DatabaseContext.cs): `src/desktop/Watcher.Infrastructure/Database/DatabaseContext.cs`
- [Repositories](https://github.com/shraman-c/watcher/tree/main/src/desktop/Watcher.Infrastructure/Repositories): `src/desktop/Watcher.Infrastructure/Repositories`
- [Legacy Config Migration](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Infrastructure/Configuration/LegacyConfigMigrator.cs): `src/desktop/Watcher.Infrastructure/Configuration/LegacyConfigMigrator.cs`
- [Activity History](https://github.com/shraman-c/watcher/blob/main/src/desktop/Watcher.Infrastructure/Repositories/ActivityRepository.cs): `src/desktop/Watcher.Infrastructure/Repositories/ActivityRepository.cs`

### Windows Integration

- [Windows Services](https://github.com/shraman-c/watcher/tree/main/src/desktop/Watcher.Infrastructure/Windows): `src/desktop/Watcher.Infrastructure/Windows`

### Other components

- **User**

## Connections

- User → React Application: uses
- React Application → Product Views: renders (evidence: `src/frontend/src/App.tsx`)
- React Application → UI State Stores: loads state (evidence: `src/frontend/src/App.tsx`)
- Product Views → UI State Stores: requests data (evidence: `src/frontend/src/pages/FoldersPage.tsx`)
- UI State Stores → Bridge Client: calls actions (evidence: `src/frontend/src/stores/useMonitoringStore.ts`)
- Bridge Client → Bridge Contracts: uses types (evidence: `src/frontend/src/services/bridgeClient.ts`)
- Bridge Client → Bridge Service: sends RPC
- Bridge Service → Desktop Host: posts messages
- Desktop Host → Folder Monitoring: starts monitoring
- Desktop Host → Bridge Service: hosts bridge
- Folder Monitoring → Repositories: loads folders (evidence: `src/desktop/Watcher.Core/Monitoring/MonitoringManager.cs`)
- Folder Monitoring → Folder Watcher: starts watchers (evidence: `src/desktop/Watcher.Core/Monitoring/MonitoringManager.cs`)
- Folder Monitoring → File Organization: organizes existing files (evidence: `src/desktop/Watcher.Core/Monitoring/MonitoringManager.cs`)
- File Organization → Rule Engine: evaluates files (evidence: `src/desktop/Watcher.Core/Organization/FileOrganizationService.cs`)
- File Organization → Readiness Detection: checks readiness (evidence: `src/desktop/Watcher.Core/Organization/FileOrganizationService.cs`)
- File Organization → Collision Handling: resolves conflicts (evidence: `src/desktop/Watcher.Core/Organization/FileOrganizationService.cs`)
- File Organization → Loop Guard: checks paths (evidence: `src/desktop/Watcher.Core/Organization/FileOrganizationService.cs`)
- Rule Engine → Default Categories: loads defaults (evidence: `src/desktop/Watcher.Core/Rules/RuleEngine.cs`)
- Repositories → SQLite Database: reads and writes (evidence: `src/desktop/Watcher.Infrastructure/Repositories/ActivityRepository.cs`)
- Bridge Service → Repositories: serves settings and rules (evidence: `src/desktop/Watcher.Desktop/Services/BridgeService.cs`)
- Bridge Service → Activity History: serves activity (evidence: `src/desktop/Watcher.Desktop/Services/BridgeService.cs`)
- Activity History → SQLite Database: persists movements (evidence: `src/desktop/Watcher.Infrastructure/Repositories/ActivityRepository.cs`)
- Legacy Config Migration → SQLite Database: migrates configuration
- Desktop Host → Legacy Config Migration: runs migration (evidence: `src/desktop/Watcher.Desktop/Program.cs`)
- Bridge Service → Windows Services: uses shell features (evidence: `src/desktop/Watcher.Desktop/Services/BridgeService.cs`)
- Windows Services → User: notifies and launches