# facebook/watchman architecture

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

- Interactive diagram: https://gitdiagram.com/facebook/watchman
- Repository: https://github.com/facebook/watchman

## Overview

##### Main Components
- Core Watcher Engine: Represent the heart of Watchman which includes the C++ core components (found in directories such as “watchman”, “fs”, “query”, “root”, “watcher”, “telemetry”, etc.). This engine is responsible for:
- Monitoring file system events (using various OS-specific mechanisms: inotify on Linux, FSEvents on macOS, Windows specific implementations, etc.)
- Collecting and processing events.
- Interfacing with the subscription and query subsystems.
- Client Interfaces: Represent the multiple language bindings (Python, Java, Rust, Node.js, Ruby) and the CLI tool (found under “watchman/cli”, “watchman/python”, “watchman/java”, “watchman/node”, “watchman/rust”, etc.). These interact with the core engine over IPC mechanisms.
- IPC and Communication Channels: The project uses domain sockets (UNIX domain sockets in “watchman/unixsocket” and similar for Windows with named pipes) for communication between the core file watcher and its clients.
- Subscription & Query Subsystems: These handle client requests such as subscribing to changes, querying file states, and returning results (visible in directories like “watchman/query” and “watchman/cmds”).
- Build & Packaging Infrastructure: The build system (CMake, fbcode_builder and associated manifest directories) orchestrates compilation and dependency management; CI pipelines ('.github/workflows') and packaging scripts ensure cross-platform support.
- Logging & Telemetry: Components for logging (e.g., “watchman/Logging.cpp”, “watchman/telemetry”) are responsible for recording runtime events and performance metrics.
- Integration and Testing Environment: Directories named “integration”, “tests”, and “build” include various integration tests, system validation scripts, and build packaging which ensure quality and cross-platform compatibility.

##### Relationships and Interactions
- The Core Watcher Engine continuously monitors for file system changes.
- When a change is detected, the Core Engine processes the event (using components from fs/, query/, and root/) and dispatches it via IPC to subscribed client interfaces.
- Clients (via libraries for Python/Java/Node/etc. and CLI tools) send queries and subscribe to events, which the engine processes and responds to.
- Logging and Telemetry systems gather statistics and information during operation, providing audit trails and insights into performance.
- The Build and Packaging components (CMake scripts, fbcode_builder, CI/CD workflows) ensure that each part of the system is built and packaged correctly for various platforms.
- Integration tests simulate real-file system operations and interactions among these components to validate correct communication and functionality.

##### Architectural Patterns and Design Principles
- Modularity: Clearly separated components (watcher engine, client interfaces, build system, logging, IPC) make the system easier to maintain.
- Client-Server Architecture: The core engine operates as a long-running service (server), while multiple language-specific clients access its functionality through standardized IPC mechanisms.
- Abstraction for Cross-Platform Support: Different directories focus on different OS-specific implementations (in “watchman/watcher” including files for inotify, kqueue, FSEvents, etc.), abstracted away from the client interface.
- Extensibility: The presence of well-organized manifests and integration tests indicates the need to easily add new language bindings and features over time.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Source
    FS["File System Changes"]:::fs

    %% Core Watcher Engine
    CE["Core Watcher Engine (C++)"]:::core

    %% IPC and Communication Channels Subgraph
    subgraph "IPC and Communication Channels"
        UDS["Unix Socket Support"]:::ipc
        WP["Windows Pipe Support"]:::ipc
        CC["Core Connection"]:::ipc
    end

    %% Subscription & Query Subsystems Subgraph
    subgraph "Subscription & Query Subsystems"
        SQP["Query Processing"]:::subs
        SCC["Cmd Handling"]:::subs
    end

    %% Client Interfaces Subgraph
    subgraph "Client Interfaces"
        CLI["CLI Tool"]:::client
        Py["Python Client"]:::client
        Jav["Java Client"]:::client
        Nod["Node.js Client"]:::client
        Rus["Rust Client"]:::client
        Rub["Ruby Client"]:::client
    end

    %% Logging & Telemetry Subgraph
    subgraph "Logging & Telemetry"
        LOG["Logging"]:::log
        TEL["Telemetry"]:::log
    end

    %% Build & Packaging Infrastructure Subgraph
    subgraph "Build & Packaging Infrastructure"
        BS["Build System (CMake & fbcode_builder)"]:::build
        CI["CI/CD Pipelines"]:::build
        PK["Packaging Scripts"]:::build
    end

    %% Integration & Testing Environment Subgraph
    subgraph "Integration & Testing Environment"
        INT["Integration Tests"]:::test
        UNIT["Unit/Functional Tests"]:::test
    end

    %% Flow connections
    FS -->|"monitors"| CE

    %% Core Engine triggers IPC channels
    CE -->|"triggers"| UDS
    CE -->|"initiates"| WP
    CE -->|"uses"| CC

    %% Core Engine interacts with Subscription & Query
    CE -->|"processes"| SQP
    CE -->|"handles"| SCC

    %% IPC channels deliver data to Client Interfaces
    UDS ---|"delivers"| CLI
    WP ---|"delivers"| Py
    CC ---|"delivers"| Jav

    %% Clients interact with Subscription/Query Subsystem (bidirectional communication)
    CLI -- "sendsQuery" --> SQP
    SQP -- "responds" --> CLI

    %% Core Engine sends logs and telemetry data
    CE -->|"logs"| LOG
    CE -->|"monitors"| TEL

    %% Build system supports Core Engine
    BS -->|"builds"| CE
    CI -->|"validatesBuild"| CE
    PK -->|"packages"| CE

    %% Integration and Testing validate system components
    INT -->|"tests"| CE
    UNIT -->|"tests"| CLI

    %% Click Events for Core Watcher Engine
    click CE "https://github.com/facebook/watchman/tree/main/watchman"

    %% Click Events for Client Interfaces
    click CLI "https://github.com/facebook/watchman/tree/main/watchman/cli"
    click Py "https://github.com/facebook/watchman/tree/main/watchman/python"
    click Jav "https://github.com/facebook/watchman/tree/main/watchman/java"
    click Nod "https://github.com/facebook/watchman/tree/main/watchman/node"
    click Rus "https://github.com/facebook/watchman/tree/main/watchman/rust"
    click Rub "https://github.com/facebook/watchman/tree/main/watchman/ruby"

    %% Click Events for IPC and Communication Channels
    click UDS "https://github.com/facebook/watchman/tree/main/watchman/java/src/com/facebook/watchman/unixsocket"
    click WP "https://github.com/facebook/watchman/tree/main/watchman/java/src/com/facebook/watchman/windowspipe"
    click CC "https://github.com/facebook/watchman/blob/main/watchman/Connect.cpp"

    %% Click Events for Subscription & Query Subsystems
    click SQP "https://github.com/facebook/watchman/tree/main/watchman/query"
    click SCC "https://github.com/facebook/watchman/tree/main/watchman/cmds"

    %% Click Events for Build & Packaging Infrastructure
    click BS "https://github.com/facebook/watchman/blob/main/CMakeLists.txt"
    click CI "https://github.com/facebook/watchman/tree/main/.github/workflows"
    click PK "https://github.com/facebook/watchman/tree/main/watchman/build/package"

    %% Click Events for Logging & Telemetry
    click LOG "https://github.com/facebook/watchman/blob/main/watchman/Logging.cpp"
    click TEL "https://github.com/facebook/watchman/tree/main/watchman/telemetry"

    %% Click Events for Integration & Testing Environment
    click INT "https://github.com/facebook/watchman/tree/main/watchman/integration"
    click UNIT "https://github.com/facebook/watchman/tree/main/watchman/test"

    %% Styles
    classDef fs fill:#FFEEAD,stroke:#FFB74D,stroke-width:2px;
    classDef core fill:#AEDFF7,stroke:#0077B6,stroke-width:2px;
    classDef ipc fill:#D0A9F5,stroke:#6A0DAD,stroke-width:2px;
    classDef client fill:#FFC9DE,stroke:#FF3366,stroke-width:2px;
    classDef subs fill:#C7F464,stroke:#A2D729,stroke-width:2px;
    classDef build fill:#FFF59D,stroke:#FBC02D,stroke-width:2px;
    classDef log fill:#E0E0E0,stroke:#9E9E9E,stroke-width:2px;
    classDef test fill:#F8BBD0,stroke:#F06292,stroke-width:2px;
```
