# yugdabgar21/keylogdetector architecture

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

- Interactive diagram: https://gitdiagram.com/yugdabgar21/keylogdetector
- Repository: https://github.com/yugdabgar21/keylogdetector

## Overview

##### Project Type and Purpose
- This is a Python-based CLI security tool (“Offline Keylogger Detection Tool for Windows”) that scans a user-specified folder for keylogger-related artifacts: suspicious file names, file contents, and running processes. It’s not a multi-service system but a single-entry script (`main.py`) orchestrating several scan components.

##### File Structure Analysis
- Top Level:
- `.github/…` – repository meta-data (issue templates, CI/CD, docs)
- `main.py` – the single Python script containing the scanner logic
- `README.md`, `LICENSE`, `CONTRIBUTING.md`, etc. – documentation
a. CLI Interface
b. File Signature Scanner
c. Heuristic Content Scanner
d. Process Checker
e. Report Generator

##### README Insights
- Dependencies: `psutil` (process enumeration), `tqdm` (progress bar), Python ≥3.7
- Inputs: target folder path, `signatures.txt` file path
- Output: timestamped CLI report with OK/warning flags

##### Main Components
a. User CLI (main.py)
b. File System (scanned directory)
c. Signatures File (`signatures.txt`)
d. File Signature Scanner (filename matching)
e. Heuristic Content Scanner (keyword search in files)
f. Process Checker (psutil-based)
g. Report Generator & CLI Output
h. External Libraries: `psutil`, `tqdm`

##### Component Interactions and Data Flow
1. User launches `main.py` → CLI prompts for inputs
2. CLI passes folder path to File Signature Scanner & Heuristic Scanner
3. File Signature Scanner reads filenames → matches against signature list
4. Heuristic Scanner opens each file → scans content for keywords
5. CLI invokes Process Checker → uses `psutil` to enumerate running processes → flags known suspects
6. All findings funnel into Report Generator → formats and prints the scan report with timestamps and counts

##### Architectural Patterns & Principles
- Single-responsibility: each conceptual scanner (filename, content, process) handles one type of detection
- Dependency injection: signature keywords read once and shared by scanners
- Tool-oriented: minimal layers, linear data flow, no persistent storage

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface
    CLI["User CLI\n(main.py)\nuses tqdm"]:::cli
    click CLI "https://github.com/yugdabgar21/keylogdetector/blob/main/main.py"

    %% Data Inputs
    SigFile["Signatures File\n(signatures.txt)"]:::data
    click SigFile "https://github.com/yugdabgar21/keylogdetector/blob/main/signatures.txt"
    Filesystem["File System\n(target folder)"]:::data

    %% Scanning Pipeline
    subgraph "Scanning Pipeline"
        FileSig["File Signature Scanner\n(filename matching)"]:::scanner
        click FileSig "https://github.com/yugdabgar21/keylogdetector/blob/main/main.py"
        HeurSig["Heuristic Content Scanner\n(keyword search)"]:::scanner
        click HeurSig "https://github.com/yugdabgar21/keylogdetector/blob/main/main.py"
        ProcChk["Process Checker\n(psutil)"]:::scanner
        click ProcChk "https://github.com/yugdabgar21/keylogdetector/blob/main/main.py"
    end

    %% Report Generation
    Report["Report Generator\n(formats & prints\nwith timestamps)"]:::report
    click Report "https://github.com/yugdabgar21/keylogdetector/blob/main/main.py"

    %% Documentation & CI/CD
    subgraph "Project Docs & CI/CD"
        Doc["README.md"]:::doc
        click Doc "https://github.com/yugdabgar21/keylogdetector/blob/main/README.md"
        CI[".github/ISSUE_TEMPLATE/"]:::doc
        click CI "https://github.com/yugdabgar21/keylogdetector/tree/main/.github/ISSUE_TEMPLATE/"
    end

    %% Data Flow
    CLI -->|"folder path, signatures.txt"| Filesystem
    CLI -->|"reads keywords"| SigFile
    SigFile --> FileSig
    Filesystem --> FileSig
    FileSig -->|"matches found"| Report

    Filesystem --> HeurSig
    SigFile --> HeurSig
    HeurSig -->|"heuristic matches"| Report

    CLI --> ProcChk
    ProcChk -->|"process list"| Report

    Report -->|"CLI output\nOK/warnings"| CLI

    %% Annotation
    NoteOffline["Offline Operation\n(no network)"]:::note
    CLI --- NoteOffline

    %% Styles
    classDef cli fill:#E8F1FF,stroke:#1A73E8,color:#1A73E8,stroke-width:2px;
    classDef scanner fill:#FFF4E5,stroke:#F29E4C,color:#F29E4C,stroke-width:2px;
    classDef data fill:#E6F4EA,stroke:#34A853,color:#34A853,stroke-width:2px;
    classDef report fill:#FCE8E6,stroke:#EA4335,color:#EA4335,stroke-width:2px;
    classDef doc fill:#F1F3F4,stroke:#5F6368,color:#5F6368,stroke-width:2px;
    classDef note fill:#FFFFFF,stroke:#000000,color:#000000,stroke-dasharray: 2 2;
```
