# abrignoni/aleapp architecture

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

- Interactive diagram: https://gitdiagram.com/abrignoni/aleapp
- Repository: https://github.com/abrignoni/aleapp

## Overview

##### Project type and purpose
- This is a standalone Python-based forensic tool called ALEAPP (Android Logs Events And Protobuf Parser).
- It provides both a CLI front-end (`aleapp.py`) and a GUI front-end (`aleappGUI.py`).
- It dynamically discovers and loads “artifact” plugins (in `scripts/artifacts/`) to parse Android artefact data from an extracted file system, archive or image, then generates HTML/TSV/timeline reports.

##### File structure
- Top-level:
- `aleapp.py` & `aleappGUI.py` – entry points for CLI and GUI.
- `requirements.txt` – Python dependencies.
- `scripts/` – core engine:
– `plugin_loader.py` – dynamic loading of `scripts/artifacts/*` modules.
– `report.py` & `artifact_report.py` – HTML report generation.
– `ilapfuncs.py` – TSV and timeline helpers.
– `filetypes/` – classification of input file types.
– `ccl/` – support for compressed logs via leveldb, proto, snappy.
– `pyinstaller/` – spec files for building executables.
– `artifacts/` – >300 plugin scripts, each defining a `__artifacts_v2__` dictionary and extraction function(s).
- The presence of CLI, GUI, plugin directory, file seeker, report modules suggests a modular, plugin-based architecture.

##### README for additional insights
- Confirms dynamic plugin architecture: each plugin registers metadata and a function to be invoked.
- Describes input types (`zip|tar|fs|gz`), output folder, HTML/TSV/timeline generation.
- Notes dependencies (Python ≥3.9, tkinter for GUI).

a. Main components
1) User Interface Layer
- CLI (`aleapp.py`)
2) Core Engine
- Argument Parser / Command Dispatcher
- FileSeeker (identifies files via `scripts/filetypes/` & `scripts/ccl/`)
- Plugin Loader (`plugin_loader.py`)
- Artifact Plugins (`scripts/artifacts/*.py`)
3) Report Generation
- HTML report (`artifact_report.py`)
- TSV & Timeline (`ilapfuncs.py`)
4) Packaging (optional)
- PyInstaller specs (`scripts/pyinstaller/*.spec`)
5) Data I/O
- Input: extracted file tree (zip|tar|fs|gz)
- Output: `report_folder/` with HTML, TSV, timeline files
b. Relationships and interactions
- User invokes CLI or GUI → Core Engine
- Core Engine parses args → initializes FileSeeker
- FileSeeker discovers candidate files → Plugin Loader
- Plugin Loader iterates `__artifacts_v2__`, for each plugin:
- Calls plugin function(files_found, report_folder, seeker, wrap_text)
- Plugin functions use `artifact_report` & `ilapfuncs` to write output
- Generated reports are stored under `report_folder`
c. Architectural patterns / design principles
- Plugin architecture (dynamic module loading, discovery by directory)
- Separation of concerns (UI vs core logic vs reporting)
- Modularization (file type detection, artifact extraction, output formatting)
- Data flow pipeline: Input → Discovery → Extraction → Reporting → Output
d. Key technologies & libraries
- Python ≥3.9 standard library (argparse, importlib)
- Tkinter (for GUI)
- PyInstaller (for packaging)
- Custom modules: `plugin_loader.py`, `filetypes`, `ccl`, `artifact_report.py`, `ilapfuncs.py`

- Blue rectangles for UI components
- Green for core engine modules
- Yellow for plugin artifacts
- Orange for report generators

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI["CLI Front-End: aleapp.py"]:::ui
        GUI["GUI Front-End: aleappGUI.py"]:::ui
        Assets["GUI Assets (icons)"]:::ui
    end

    %% Core Engine
    subgraph "Core Engine"
        Parser["Argument Parser / Command Dispatcher"]:::core
        FileSeeker["FileSeeker"]:::core
        PluginLoader["Plugin Loader"]:::core
    end

    %% Plugin Artifacts
    subgraph "Plugin Artifacts"
        PLUGINS["scripts/artifacts/\n(300+ plugins)"]:::plugin
        ExamplePlugin["Example Plugin: WhatsApp.py"]:::plugin
    end

    %% Reporting
    subgraph "Reporting"
        Orchestrator["General Report Orchestration"]:::report
        AR_REPORT["HTML Report Core"]:::report
        TSV["TSV & Timeline Helpers"]:::report
        HTMLPARTS["HTML Template Parts"]:::report
        ICONS["Report Icons Definitions"]:::report
    end

    %% Packaging (Optional)
    subgraph "Packaging (Optional)"
        ALEAPPSpec["aleapp.spec"]:::package
        ALEAPPGUISpec["aleappGUI.spec"]:::package
    end

    %% Data I/O
    Input(("Input: zip|tar|fs|gz")):::data
    Output(("Output: report_folder")):::data

    %% Connections
    CLI -->|invokes| Parser
    GUI -->|invokes| Parser
    Parser -->|loads files| FileSeeker
    FileSeeker -->|discovers files| PluginLoader
    PluginLoader -->|loads modules| PLUGINS
    PLUGINS -->|executes| ExamplePlugin
    Input -->|provides data| FileSeeker
    ExamplePlugin -->|writes data| AR_REPORT
    ExamplePlugin -->|writes data| TSV
    AR_REPORT -->|uses templates/icons| HTMLPARTS
    AR_REPORT -->|uses templates/icons| ICONS
    Orchestrator -->|coordinates| AR_REPORT
    Parser -->|triggers| Orchestrator
    AR_REPORT -->|outputs reports| Output
    TSV -->|outputs reports| Output

    %% Click Events
    click CLI "https://github.com/abrignoni/aleapp/blob/main/aleapp.py"
    click GUI "https://github.com/abrignoni/aleapp/blob/main/aleappGUI.py"
    click Assets "https://github.com/abrignoni/aleapp/blob/main/assets/icon.icns"
    click FileSeeker "https://github.com/abrignoni/aleapp/blob/main/scripts/search_files.py"
    click PluginLoader "https://github.com/abrignoni/aleapp/blob/main/scripts/plugin_loader.py"
    click PLUGINS "https://github.com/abrignoni/aleapp/tree/main/scripts/artifacts/"
    click ExamplePlugin "https://github.com/abrignoni/aleapp/blob/main/scripts/artifacts/WhatsApp.py"
    click AR_REPORT "https://github.com/abrignoni/aleapp/blob/main/scripts/artifact_report.py"
    click Orchestrator "https://github.com/abrignoni/aleapp/blob/main/scripts/report.py"
    click TSV "https://github.com/abrignoni/aleapp/blob/main/scripts/ilapfuncs.py"
    click HTMLPARTS "https://github.com/abrignoni/aleapp/blob/main/scripts/html_parts.py"
    click ICONS "https://github.com/abrignoni/aleapp/blob/main/scripts/report_icons.py"
    click ALEAPPSpec "https://github.com/abrignoni/aleapp/blob/main/scripts/pyinstaller/aleapp.spec"
    click ALEAPPGUISpec "https://github.com/abrignoni/aleapp/blob/main/scripts/pyinstaller/aleappGUI.spec"

    %% Styles
    classDef ui fill:#blue,stroke:#000,color:#fff
    classDef core fill:#8fbc8f,stroke:#000,color:#000
    classDef plugin fill:#f4c542,stroke:#000,color:#000
    classDef report fill:#ff8c00,stroke:#000,color:#000
    classDef package fill:#9370db,stroke:#000,color:#fff
    classDef data fill:#d3d3d3,stroke:#000,color:#000,shape:rounded
    class Input,Output data
    class CLI,GUI,Assets ui
    class Parser,FileSeeker,PluginLoader core
    class PLUGINS,ExamplePlugin plugin
    class Orchestrator,AR_REPORT,TSV,HTMLPARTS,ICONS report
    class ALEAPPSpec,ALEAPPGUISpec package
```
