# alexforman1/forensicscanner architecture

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

- Interactive diagram: https://gitdiagram.com/alexforman1/forensicscanner
- Repository: https://github.com/alexforman1/forensicscanner

## Overview

##### Project Type and Purpose
- ForensicScanner is a Python-based desktop application (CLI + GUI) for offline forensic log analysis.
- It processes various log formats, applies pattern-based detection, and augments results with local LLM inference.

##### File Structure
- Top-level entry points:
- main.py – CLI launcher
- gui.py – GUI launcher
- Core modules (duplicated in src/ and root):
- log_parser.py – pattern matching engine
- ai_analyzer.py – local LLM integration
- searcher.py – search/filter logic
- summarize.py – report/summarization
- config/ – baseline rules, network rules
- models/ – directory for GGUF LLM files
- logs/ – runtime logs and test samples
- src/utils/ – shared helper functions (memory management, I/O)
- settings.json – user defaults
- requirements.txt – Python dependencies

##### Main Components and Responsibilities
A. User Interfaces
­– CLI Interface (main.py)
­– Tkinter GUI (gui.py + src/gui/)
B. Core Engines (backend)
­– Log Parser: reads file → tokenizes → pattern matching → severity scoring
­– AI Analyzer: loads local GGUF model → context-aware analysis → recommendations
­– Searcher: filters findings (severity, category, time window)
­– Summarizer: aggregates and formats final report
C. Configuration Layer
­– settings.json, baseline.yaml, network_rules.json → parameterize parsing & scoring
D. Model Storage
­– models/ directory hosting .gguf files (Mistral, Llama)
E. Logging & Persistence
­– logs/ directory for audit trail, debugging
F. Utilities
­– src/utils for resource monitoring (psutil), chunked file I/O, common helpers

##### Component Interactions and Data Flow
1. User invokes CLI or GUI →
2. CLI/GUI launcher loads settings.json and config files →
3. File input passed to Log Parser →
4. Parser emits structured events/findings →
5. Findings flow into AI Analyzer (optional) →
6. Combined results fed to Searcher & Summarizer →
7. Output displayed (GUI panel or terminal via rich) and/or saved to disk →
8. Every step logs to logs/*.log for audit

##### Architectural Patterns and Principles
- Modular Pipeline: discrete stages (parsing → AI → filtering → summarization)
- Plug-in Style: AI models are drop-in (.gguf), rules configurable via YAML/JSON
- Separation of Concerns: UI vs. core logic vs. configuration vs. persistence
- Resource Efficiency: chunked processing, multi-threading, memory threshold monitoring

##### Relevant Technologies & Libraries
- Python 3.8+
- llama-cpp-python for local GGUF inference
- Tkinter (tkinterdnd2) for GUI + drag-and-drop
- rich for CLI output formatting
- psutil for system resource monitoring
- pandas (optional) for data manipulation in summarization

##### Final Advice
- Be exhaustive: capture all core modules and data flows.
- Fallback paths: e.g., AI Analyzer is optional if no model present.
- Resource-monitoring loop around heavy stages (parser, AI).
- Thread usage and chunked processing for performance clarity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        direction TB
        CLI["CLI Launcher"]:::ui
        GUI["GUI Launcher"]:::ui
    end

    %% Configuration and Models
    subgraph "Configuration & Models"
        direction TB
        ConfigFiles["Configuration Files"]:::config
        Models["Model Storage"]:::storage
    end

    %% Core Pipeline
    subgraph "Core Engines"
        direction TB
        Parser["Log Parser"]:::core
        AI["AI Analyzer (optional)"]:::core
        Searcher["Searcher"]:::core
        Summarizer["Summarizer"]:::core
    end

    %% Output & Logging
    subgraph "Output & Persistence"
        direction TB
        Output["Results (Terminal/GUI)"]:::ui
        Logs["Logs Directory"]:::storage
    end

    %% Utilities
    Utils["Utilities"]:::utils

    %% Data Flow
    CLI -->|invoke| ConfigFiles
    GUI -->|invoke| ConfigFiles
    ConfigFiles -->|load settings/rules| Parser
    Models -->|load GGUF model| AI
    Parser -->|parse & tokenize| AI
    Parser -->|emit findings| Searcher
    AI -->|analyze findings| Searcher
    Searcher -->|filter & categorize| Summarizer
    Summarizer -->|format report| Output
    Output -->|display/save| Logs
    Parser -->|log events| Logs
    AI -->|log events| Logs
    Searcher -->|log events| Logs
    Summarizer -->|log events| Logs

    %% Resource Monitoring Loop
    Parser -->|monitor resources| Utils
    AI -->|monitor resources| Utils

    %% Click Events
    click CLI "https://github.com/alexforman1/forensicscanner/blob/main/main.py"
    click GUI "https://github.com/alexforman1/forensicscanner/blob/main/gui.py"
    click GUI "https://github.com/alexforman1/forensicscanner/tree/main/src/gui/"
    click Parser "https://github.com/alexforman1/forensicscanner/blob/main/log_parser.py"
    click Parser "https://github.com/alexforman1/forensicscanner/blob/main/src/log_parser.py"
    click AI "https://github.com/alexforman1/forensicscanner/blob/main/ai_analyzer.py"
    click AI "https://github.com/alexforman1/forensicscanner/blob/main/src/ai_analyzer.py"
    click Searcher "https://github.com/alexforman1/forensicscanner/blob/main/searcher.py"
    click Summarizer "https://github.com/alexforman1/forensicscanner/blob/main/summarize.py"
    click ConfigFiles "https://github.com/alexforman1/forensicscanner/blob/main/config/baseline.yaml"
    click ConfigFiles "https://github.com/alexforman1/forensicscanner/blob/main/config/network_rules.json"
    click ConfigFiles "https://github.com/alexforman1/forensicscanner/blob/main/settings.json"
    click Models "https://github.com/alexforman1/forensicscanner/tree/main/models/"
    click Logs "https://github.com/alexforman1/forensicscanner/tree/main/logs/"
    click Utils "https://github.com/alexforman1/forensicscanner/tree/main/src/utils/"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef core fill:#DFFFE0,stroke:#28A745,color:#28A745
    classDef config fill:#FFF5CC,stroke:#D4A017,color:#D4A017
    classDef storage fill:#F0F0F0,stroke:#6A737D,color:#6A737D
    classDef utils fill:#FFE0CC,stroke:#D73A49,color:#D73A49
```
