# paulmillr/chokidar architecture

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

- Interactive diagram: https://gitdiagram.com/paulmillr/chokidar
- Repository: https://github.com/paulmillr/chokidar

## Overview

##### Main Components

a) Core Components:
- File System Interface Layer
- Event Normalization Engine
- Watcher Manager
- Event Emitter System

b) Supporting Components:
- Configuration Handler
- Path Filter System
- Stats Collection System

**[Application Layer (Consumer)]**
- ↕
**[Chokidar Public API]**
- ↕
**[Watcher Manager]**
- ↙     ↓     ↘
**[FS Watch] [FS WatchFile] [Stats Collector]**
- ↓
**[Event Normalizer]**
- ↓
**[Native FS API]**

##### Component Details

a) Public API Layer:
- Main `watch()` method
- FSWatcher instance methods (add, unwatch, close, getWatched)
- Event emission capabilities (add, change, unlink, etc.)

b) Watcher Manager:
- Decision logic between fs.watch and fs.watchFile
- Configuration options handling
- Path management system

c) Event Processing:
- Event normalization flow
- Atomic write detection
- Chunked write handling

##### Specific Implementation Details

- Rectangles: Core components
- Rounded rectangles: APIs and interfaces
- Hexagons: Decision points
- Blue: Core functionality
- Green: File system operations
- Yellow: Event handling
- Gray: Configuration and utilities

##### Important Relationships to Highlight

- How the watching strategies (polling vs. native) are selected
- Event normalization process
- Path filtering system
- How atomic and chunked writes are handled

##### Configuration Flow

How options affect the system:
- usePolling
- awaitWriteFinish
- ignored paths
- atomic writes
- depth limitations

This design should reflect Chokidar's v4 architecture, which has been simplified to have only one dependency and focuses on core file watching functionality without glob support.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Legend
        A[Core Component]:::core
        B([API/Interface]):::api
        C{{Decision Point}}:::decision
        D[(File System)]:::fs
        E[/Event Flow/]:::event
    end

    subgraph "Application Layer"
        Consumer([Consumer Application]):::api
    end

    subgraph "Chokidar Public API"
        API([FSWatcher Public Interface]):::api
        Methods([".add()\n.unwatch()\n.close()\n.getWatched()"]):::api
    end

    subgraph "Watcher Manager"
        WatchManager[Watcher Manager]:::core
        Config{{Configuration Handler}}:::decision
        Strategy{{Watch Strategy Selector}}:::decision
    end

    subgraph "File System Watchers"
        FSWatch[Native fs.watch]:::fs
        FSWatchFile[fs.watchFile Polling]:::fs
        StatsCollector[Stats Collection System]:::fs
    end

    subgraph "Event Processing"
        EventNorm[Event Normalizer]:::core
        AtomicWrite{{Atomic Write Detection}}:::decision
        ChunkedWrite{{Chunked Write Handler}}:::decision
    end

    subgraph "Native Layer"
        NativeFS[(Node.js FS API)]:::fs
    end

    Consumer --> API
    API --> Methods
    API --> WatchManager
    WatchManager --> Config
    Config --> Strategy
    Strategy --> |Native| FSWatch
    Strategy --> |Polling| FSWatchFile
    Strategy --> StatsCollector
    FSWatch --> EventNorm
    FSWatchFile --> EventNorm
    StatsCollector --> EventNorm
    EventNorm --> AtomicWrite
    EventNorm --> ChunkedWrite
    AtomicWrite --> |Normalized Events| API
    ChunkedWrite --> |Normalized Events| API
    FSWatch --> NativeFS
    FSWatchFile --> NativeFS

    classDef core fill:#2374ab
    classDef api fill:#47a025,rx:10
    classDef decision fill:#ffb347,shape:hexagon
    classDef fs fill:#808080
    classDef event fill:#ffd700

    click API "https://github.com/paulmillr/chokidar/blob/main/src/index.ts"
    click EventNorm "https://github.com/paulmillr/chokidar/blob/main/src/handler.ts"
    click Consumer "https://github.com/paulmillr/chokidar/blob/main/example.js"
    click Config "https://github.com/paulmillr/chokidar/blob/main/tsconfig.json"
    click WatchManager "https://github.com/paulmillr/chokidar/blob/main/src/index.ts"
    click Methods "https://github.com/paulmillr/chokidar/blob/main/src/index.ts"
```
