# gorakhargosh/watchdog architecture

> Architecture diagram of the GitHub repository gorakhargosh/watchdog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gorakhargosh/watchdog
- Repository: https://github.com/gorakhargosh/watchdog

## Overview

##### Main Components
- API Layer: This is where users interact with the library (via function calls and event handler classes).
- Observer Abstraction: Representing the core “observer” interface that all concrete observers implement.
- Platform-Specific Observer Implementations: Sub-components like “inotify”, “fsevents”, “kqueue”, “polling”, “winapi” (each in their own module under src/watchdog/observers).
- Event Handling: Components such as the FileSystemEvent objects and event handler base class. This is what user-defined handlers subclass.
- Utility/CLI Component: The “watchmedo” tool and its associated modules which provide a command-line interface and hooks to use “tricks” (in src/watchdog/watchmedo.py and src/watchdog/tricks).
- Utility Functions: Helper modules (in src/watchdog/utils), which include functionality like event debouncing, pattern matching, and process watching.
- Supporting Tools & Tests: Although not necessarily part of runtime architecture, the tests and docs directories help validate behavior and usage.

##### Out the Relationships and Interactions
- The API layer enables users to create an Observer instance, schedule event handler callbacks, and start/stop monitoring.
- The Observer then defers to one of the platform-specific modules (e.g., inotify, polling, winapi, etc.) based on the operating system.
- File system events, which are captured by these observers, are passed back to the appropriate event handlers.
- The “watchmedo” command-line utility is built on top of the API and ties CLI commands (like “log” or “shell-command”) to corresponding event handler triggers. It also supports reading “tricks.yaml” for more complex event-triggered behaviors.

##### Architectural Patterns and Design Principles
- Abstraction & Polymorphism: The design abstracts the observer pattern (with a common Observer interface and multiple concrete implementations).
- Dependency Injection: Users can customize event handlers by subclassing the provided FileSystemEventHandler.
- Separation of Concerns: The library cleanly separates the event detection (observers), event processing (handlers and utilities), and command-line interactions (watchmedo).

##### Technologies and Frameworks
- Python 3.9+ is the runtime.
- Specific OS interfaces/APIs (e.g., Linux’s inotify, macOS’s FSEvents) interfaced through Python.
- YAML processing (via PyYAML) for reading the “tricks.yaml” files in the watchmedo component.
- Testing frameworks and build tools (tox, pytest, etc.) indicated in the tests folder and config files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entity
    OS["Operating System/File System"]:::external

    %% User Interface Layer
    subgraph "User Interface Layer"
        API["Watchdog API"]:::api
        CLI["watchmedo CLI"]:::cli
    end

    %% Observer Layer
    subgraph "Observer Layer"
        OBS_IF["Observer Interface"]:::observer
        INOT["Inotify Observer"]:::observer
        FSEV["FSEvents Observer"]:::observer
        KQUE["Kqueue Observer"]:::observer
        POLL["Polling Observer"]:::observer
        WIN["WinAPI Observer"]:::observer
    end

    %% Event Handling Layer
    subgraph "Event Handling Layer"
        EVH["Event Classes & Base Handler"]:::handler
    end

    %% Utility Modules
    subgraph "Utility Modules"
        UTIL["Utility Functions"]:::utility
    end

    %% Supporting Tools & Tests
    subgraph "Supporting Tools"
        TEST["Tests & Documentation"]:::test
    end

    %% Connections
    OS -->|"triggers"| OBS_IF

    OBS_IF -->|"if Linux"| INOT
    OBS_IF -->|"if macOS"| FSEV
    OBS_IF -->|"if BSD"| KQUE
    OBS_IF -->|"if unsupported"| POLL
    OBS_IF -->|"if Windows"| WIN

    INOT -->|"sends events"| EVH
    FSEV -->|"sends events"| EVH
    KQUE -->|"sends events"| EVH
    POLL -->|"sends events"| EVH
    WIN -->|"sends events"| EVH

    API -->|"creates & schedules"| OBS_IF
    API -->|"registers handlers"| EVH
    CLI -->|"invokes"| API

    UTIL ---|"supports"| OBS_IF
    UTIL ---|"supports"| EVH

    TEST ---|"tests"| API
    TEST ---|"tests"| OBS_IF
    TEST ---|"tests"| EVH

    %% Click Events
    click API "https://github.com/gorakhargosh/watchdog/blob/master/src/watchdog/__init__.py"
    click API "https://github.com/gorakhargosh/watchdog/blob/master/src/watchdog/events.py"
    click OBS_IF "https://github.com/gorakhargosh/watchdog/blob/master/src/watchdog/observers/api.py"
    click INOT "https://github.com/gorakhargosh/watchdog/blob/master/src/watchdog/observers/inotify.py"
    click FSEV "https://github.com/gorakhargosh/watchdog/blob/master/src/watchdog/observers/fsevents.py"
    click KQUE "https://github.com/gorakhargosh/watchdog/blob/master/src/watchdog/observers/kqueue.py"
    click POLL "https://github.com/gorakhargosh/watchdog/blob/master/src/watchdog/observers/polling.py"
    click WIN "https://github.com/gorakhargosh/watchdog/blob/master/src/watchdog/observers/winapi.py"
    click EVH "https://github.com/gorakhargosh/watchdog/blob/master/src/watchdog/events.py"
    click CLI "https://github.com/gorakhargosh/watchdog/blob/master/src/watchdog/watchmedo.py"
    click CLI "https://github.com/gorakhargosh/watchdog/tree/master/src/watchdog/tricks"
    click UTIL "https://github.com/gorakhargosh/watchdog/tree/master/src/watchdog/utils"
    click TEST "https://github.com/gorakhargosh/watchdog/tree/master/tests"

    %% Styles
    classDef api fill:#bbf,stroke:#333,stroke-width:2px;
    classDef cli fill:#ffc107,stroke:#333,stroke-width:2px;
    classDef observer fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef handler fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef utility fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef test fill:#f94144,stroke:#333,stroke-width:2px;
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:2px;
```
