# itztron/file-change-monitor architecture

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

- Interactive diagram: https://gitdiagram.com/itztron/file-change-monitor
- Repository: https://github.com/itztron/file-change-monitor

## Overview

##### Project Type and Purpose
- This is a standalone Python utility (not a multi-service or full-stack app).
- Purpose: Monitor one or more files for modifications or deletions by hashing file contents at intervals (or on demand), and log any changes.

##### Main Components
a. Input Manager
- Command-Line Parser (argparse or sys.argv)
- Interactive Prompt (stdin reader)
b. File Monitor Core
- File List Registry (in-memory list of file paths)
- Hashing Engine (calculates current SHA-256 hash)
- Comparator (compares old vs. new hash)
c. Event Detector
- Modification Detector (hash mismatch)
- Deletion Detector (file missing)
d. Logger
- Log Formatter (timestamp, file path, event type)
- Log Writer (appends to file_changes.log)
e. Control Flow / Loop
- Main Loop (polling or event-driven)
- Graceful Shutdown Handler (Ctrl+C trap)

##### External Dependencies and Resources
- Operating System File System (where target files reside)
- Local Log File (`file_changes.log`)
- Python standard library (os, hashlib, time, signal, sys)

##### Relationships & Data Flow
- User → Input Manager → File List Registry
- File List Registry → Hashing Engine → Comparator → Event Detector
- Event Detector → Logger → Log File
- Control Flow → loops through Hashing Engine at fixed intervals (or triggered by file change events if extended)

##### Architectural Patterns & Principles
- Single Responsibility: each module (input, hashing, comparing, logging) does one job.
- Separation of Concerns: input management is decoupled from monitoring logic and logging.
- Graceful Shutdown: handle OS signals for cleanup.

##### Essential Elements Checklist
[ ] Clear, self-descriptive labels on every component
[ ] Shutdown/Signal-handler path highlighted

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::userFacing

    subgraph "Input Manager"
        CLI["CLI Parser"]:::userFacing
        IP["Interactive Prompt"]:::userFacing
    end

    subgraph "File Monitor Core"
        FLR["File List Registry"]:::coreLogic
        HE["Hashing Engine"]:::coreLogic
        CMP["Comparator"]:::coreLogic
    end

    subgraph "Event Detector"
        MD["Modification Detector"]:::coreLogic
        DD["Deletion Detector"]:::coreLogic
    end

    subgraph "Logger"
        LF["Log Formatter"]:::logging
        LW["Log Writer"]:::logging
    end

    subgraph "Control Flow"
        ML["Main Loop"]:::coreLogic
        SH["Shutdown Handler"]:::coreLogic
    end

    FS[(OS File System)]:::externalSystems
    LFFile[(file_changes.log)]:::externalSystems

    Docs["Documentation"]:::externalSystems
    README["README.md"]:::externalSystems
    LICENSE["LICENSE"]:::externalSystems

    User --> CLI
    User --> IP
    CLI --> FLR
    IP --> FLR
    FLR --> HE
    FS --> HE
    HE --> CMP
    CMP --> MD
    CMP --> DD
    MD --> LF
    DD --> LF
    LF --> LW
    LW --> LFFile
    ML --> HE
    SH -.-> User
    Docs --> README
    Docs --> LICENSE

    click CLI "https://github.com/itztron/file-change-monitor/blob/main/file_monitor_1.py"
    click IP "https://github.com/itztron/file-change-monitor/blob/main/file_monitor_1.py"
    click FLR "https://github.com/itztron/file-change-monitor/blob/main/file_monitor_1.py"
    click HE "https://github.com/itztron/file-change-monitor/blob/main/file_monitor_1.py"
    click CMP "https://github.com/itztron/file-change-monitor/blob/main/file_monitor_1.py"
    click MD "https://github.com/itztron/file-change-monitor/blob/main/file_monitor_1.py"
    click DD "https://github.com/itztron/file-change-monitor/blob/main/file_monitor_1.py"
    click LF "https://github.com/itztron/file-change-monitor/blob/main/file_monitor_1.py"
    click LW "https://github.com/itztron/file-change-monitor/blob/main/file_monitor_1.py"
    click ML "https://github.com/itztron/file-change-monitor/blob/main/file_monitor_1.py"
    click SH "https://github.com/itztron/file-change-monitor/blob/main/file_monitor_1.py"
    click README "https://github.com/itztron/file-change-monitor/blob/main/README.md"
    click LICENSE "https://github.com/itztron/file-change-monitor/tree/main/LICENSE"

    classDef userFacing fill:#add8e6,stroke:#000,stroke-width:1px
    classDef coreLogic fill:#90ee90,stroke:#000,stroke-width:1px
    classDef logging fill:#ffffe0,stroke:#000,stroke-width:1px
    classDef externalSystems fill:#d3d3d3,stroke:#000,stroke-width:1px
```
