# arxsys/dff architecture

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

- Interactive diagram: https://gitdiagram.com/arxsys/dff
- Repository: https://github.com/arxsys/dff

## Overview

##### Project type and purpose
- Project type: Open-source, modular digital forensics platform
- Purpose: Provide a core C/C++ API for low-level disk and file-system access, extendable via Python-based modules, with both CLI and Qt-based GUI frontends, to automate forensic analysis and generate reports.

##### File structure
- Top-level: build scripts and configuration (CMakeLists.txt, cmake_modules/, dff-build.sh)
- Core code: `dff/` – contains CMakeLists (to build the C/C++ API), SWIG interfaces (`__init__.py.in`), and subpackages:
- api/ – Python wrappers over the core API
- modules/ – Python-based forensic plugins (file-system parsers, metadata extractors, viewers)
- ui/ – Qt GUI components (widgets, windows)
- unsupported/ – experimental or legacy modules
- Frontends: `dff.py` (CLI), `dff-gui.py` (GUI launcher)
- Tests: testsuite/ with unit tests and data sets
- Documentation: doc/, README.md, Doxyfile

##### README insights
- Modular architecture: core + modules
- Scriptability: Python API and command-line interface
- Genericity: OS-agnostic core using libbfio, libewf, libpff, libvshadow
- Key features implemented as modules (filesystem mounts, metadata extraction, timeline, Volatility integration)

##### Main components and relationships
a. Components
1. Core Forensics Engine (C/C++ API)
2. SWIG-generated Python Bindings
3. Plugin Modules (Python)
4. Frontends: CLI (`dff.py`) and GUI (`dff-gui.py` + Qt)
5. External Forensic Libraries (libbfio, libewf, libpff, libvshadow)
6. Optional Extensions (Volatility, PyRegfi, pefile)
7. Test Harness (testsuite/)
b. Interactions
- Frontends invoke Python Bindings → call Core API
- Plugin Modules register with the API, receive data handles, process forensic images
- Core API calls into external C libraries for image and filesystem I/O
- Modules may call optional Python libraries (Volatility, pefile)
- Output modules generate HTML reports, extracted files, timelines
- Tests directly invoke the Python API to verify module behavior
c. Architectural patterns
- Layered architecture:
Layer 1: External Forensic I/O Libraries
Layer 2: Core API (C/C++)
Layer 3: Python Bindings (SWIG)
Layer 4: Plugin Modules
Layer 5: Frontends (CLI/GUI)
- Plugin pattern: modules conform to a common API and can be dynamically loaded
- MV* in the GUI: Qt widgets (View), module controllers (Controller), data model provided by the Core API
d. Key technologies
- Build: CMake, SWIG, Python-Qt4
- Core dependencies: libbfio, libewf, libpff, libvshadow
- Scripting: Python 2.7 with PyQt4
- GUI: Qt4 via PyQt4
- Testing: unittest framework, custom test data

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Libraries Layer
    EL["External I/O Libraries<br/>(libbfio, libewf, libpff, libvshadow)"]:::external

    %% Core API Layer
    CA["Core Forensics Engine<br/>(C/C++ API)"]:::core

    %% SWIG & Python Layer
    SB["SWIG Python Bindings"]:::python
    PA["Python API Wrappers"]:::python

    %% Plugin Modules
    PM["Plugin Modules"]:::python

    %% Frontends
    CLI["CLI Frontend<br/>(dff.py)"]:::python
    GL["GUI Launcher<br/>(dff-gui.py)"]:::python
    UI["Qt GUI Components"]:::python

    %% Optional Extensions
    VOL["Optional Extensions<br/>(Volatility, PyRegfi, pefile)"]:::optional

    %% Test Harness
    TH["Test Harness<br/>(testsuite/)"]:::test

    %% Outputs
    HR["HTML Reports"]:::output
    EF["Extracted Files Store"]:::output
    TL["Timeline Output"]:::output

    %% Build & Documentation
    BC["Build Config & Scripts"]:::docs
    DOC["Documentation"]:::docs
    RES["Resource Files"]:::docs

    %% Data Flow
    CLI -->|"invoke API"| SB
    GL -->|"invoke API"| SB
    UI -->|"invoke Qt APIs"| SB
    TH -->|"test API"| PA
    SB -->|"calls Core"| CA
    PA -->|"wraps Core"| SB
    CA -->|"uses I/O"| EL
    PA -->|"registers modules"| PM
    PM -->|"generate"| HR
    PM -->|"generate"| EF
    PM -->|"generate"| TL
    PM -.->|"optional use"| VOL

    %% Build & Docs Connections
    BC --> CA
    BC --> SB
    BC --> PM
    DOC --> CLI
    DOC --> GUI
    RES --> UI

    %% Click Events
    click CA "https://github.com/arxsys/dff/tree/develop/dff/"
    click SB "https://github.com/arxsys/dff/blob/develop/dff/__init__.py.in"
    click PA "https://github.com/arxsys/dff/tree/develop/dff/api/"
    click PM "https://github.com/arxsys/dff/tree/develop/dff/modules/"
    click UI "https://github.com/arxsys/dff/tree/develop/dff/ui/"
    click VOL "https://github.com/arxsys/dff/tree/develop/dff/unsupported/"
    click CLI "https://github.com/arxsys/dff/blob/develop/dff.py"
    click GL "https://github.com/arxsys/dff/blob/develop/dff-gui.py"
    click BC "https://github.com/arxsys/dff/blob/develop/CMakeLists.txt"
    click DOC "https://github.com/arxsys/dff/tree/develop/doc/"
    click RES "https://github.com/arxsys/dff/tree/develop/ressources/"
    click TH "https://github.com/arxsys/dff/tree/develop/testsuite/"

    %% Styles
    classDef core fill:#cde5f7,stroke:#2a5f94,color:#000;
    classDef python fill:#e5f7cd,stroke:#5f942a,color:#000;
    classDef external fill:#f7e5cd,stroke:#94412a,color:#000;
    classDef optional fill:#e0e0e0,stroke:#888,color:#000,stroke-dasharray: 5 5;
    classDef output fill:#f0f7e5,stroke:#4a7a2b,color:#000;
    classDef test fill:#f7d7e5,stroke:#942a5f,color:#000;
    classDef docs fill:#f7f7d7,stroke:#7a7a4a,color:#000;
```
