# abrignoni/ileapp architecture

> Architecture diagram of the GitHub repository abrignoni/ileapp, 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/ileapp
- Repository: https://github.com/abrignoni/ileapp

## Overview

##### Project type and purpose
- This is an open-source forensic analysis tool (iLEAPP) written in Python.
- It provides both a CLI (ileapp.py) and a GUI (ileappGUI.py) for parsing iOS/iPadOS logs, events, plists, and generating reports (HTML, TSV, LAVA, timeline, optional KML).
- It is extensible via a plugin architecture: each artifact extractor lives as a Python module in scripts/artifacts/.

##### High-level file-structure analysis
- Top-level:
- ileapp.py (CLI entry point)
- ileappGUI.py (tkinter-based GUI entry point)
- requirements.txt (Python dependencies)
- .github/workflows/… (CI jobs: updating module info, generating filepath search summaries)
- whl_files/… (binary wheels Python components depend on)
- scripts/: core engine and helpers
- plugin_loader.py (discovers & loads artifacts from scripts/artifacts/)
- ilapfuncs.py, artifact_report.py (utilities for parsing & report generation)
- filetype.py, search_files.py, tz_offset.py, etc.
- ccl/, keychain/, ktx/ (sub-libraries for decompression/file formats)
- filetypes/ (file-mimetype classification)
- pyinstaller/ (spec files for building standalone executables)
- scripts/artifacts/: ~400 modules, each defines a __artifacts_v2__ metadata dict and a processing function.
- admin/: developer docs, data lists, module-info scripts, test cases, test result artifacts.

##### README insights
- Describes supported iOS versions, usage (CLI vs GUI), build steps (pyinstaller), plugin metadata format, and test guidelines.
- Emphasizes dynamic loading of artifact modules via a __artifacts_v2__ API.

##### Main components & relationships
A. Frontends
– CLI (ileapp.py)
– GUI (ileappGUI.py using tkinter + embedded webview)
B. Core “engine”
1. FileSeeker abstraction (handles zip, tar, FS, backup folders)
2. PluginLoader (loads every Python file in scripts/artifacts/)
3. Artifact processor functions (one per artifact module)
4. Utility layers:
- ilapfuncs.py (common parsing helpers)
- artifact_report.py (HTML/TSV/LAVA/timeline output)
- filetype.py, parse3.py, chat_rendering.py, etc.
5. Report output directory (HTML, data files, timeline JSON, optional KML)
C. Packaging
– PyInstaller spec files to produce Windows .exe and macOS .app executables
D. Testing & Admin
– admin/test/ (JSON test definitions + sample zipped input files)
– admin/scripts/ (scripts to generate module info, filepath summaries)
– CI workflows (.github/workflows) depend on those admin scripts

##### Architectural patterns & design principles
- Plugin-based, dynamic loading: loose coupling between core engine and artifact modules
- Layered architecture:
1. Presentation (CLI / GUI)
2. Application core (FileSeeker, PluginLoader)
3. Domain (artifact processors)
4. Infrastructure (file I/O, compression libraries, external dependencies)
5. Reporting (HTML, TSV, LAVA, timeline)
- Single responsibility: each artifact module handles exactly one data-extraction concern

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        CLI["CLI Frontend\nileapp.py"]:::frontend
        GUI["GUI Frontend\nileappGUI.py"]:::frontend
    end

    %% Core Engine Layer
    subgraph "Core Engine"
        direction TB
        FileSeeker["FileSeeker\n(scripts/search_files.py)"]:::core
        PluginLoader["PluginLoader\n(scripts/plugin_loader.py)"]:::core
    end

    %% Plugins Layer
    subgraph "Extension Plugins"
        direction TB
        ArtifactModules["Artifact Modules\n(scripts/artifacts/)"]:::plugins
    end

    %% Utility Layer
    subgraph "Utility Layer"
        direction TB
        ILAPFUNCS["Parsing Helpers\n(scripts/ilapfuncs.py)"]:::utility
        FileType["File-type Classification\n(scripts/filetype.py)"]:::utility
        Parse3["Advanced Parsing\n(scripts/parse3.py)"]:::utility
        ChatRender["Chat Rendering Helpers\n(scripts/chat_rendering.py)"]:::utility
        LavaFuncs["LAVA Output Helpers\n(scripts/lavafuncs.py)"]:::utility
        ArtifactReport["Report Generator\n(scripts/artifact_report.py)"]:::utility
    end

    %% Reporting Output
    Output["Report Output\n(HTML, TSV, LAVA, timeline, KML)"]:::output

    %% Packaging Layer
    subgraph "Packaging"
        direction TB
        SpecCLI["ileapp.spec"]:::packaging
        SpecGUI["ileappGUI.spec"]:::packaging
        SpecCLI_MAC["ileapp_macOS.spec"]:::packaging
        SpecGUI_MAC["ileappGUI_macOS.spec"]:::packaging
    end

    %% Dev/Admin & CI Layer
    subgraph "Dev/Admin & CI"
        direction TB
        CI1["update_module_info.yml"]:::dev
        CI2["filepath_search_summary.yml"]:::dev
        AdminDocs["Admin Docs & Scripts\n(admin/docs/, admin/scripts/)"]:::dev
        TestCases["Test Definitions\n(admin/test/cases/)"]:::dev
        TestRunner["Test Runner Scripts\n(admin/test/scripts/)"]:::dev
    end

    %% External Dependencies
    External["External Deps\n(Python, tkinter, third-party libs)"]:::external

    %% Connections - Presentation to Core
    CLI -->|"invokes"| FileSeeker
    GUI -->|"invokes"| FileSeeker

    %% Core internal flow
    FileSeeker -->|"discovers files"| PluginLoader
    PluginLoader -->|"loads modules"| ArtifactModules

    %% Plugins to Utility
    ArtifactModules -->|"use helpers"| ILAPFUNCS
    ArtifactModules -->|"use file-type"| FileType
    ArtifactModules -->|"use parsing"| Parse3
    ArtifactModules -->|"use chat render"| ChatRender
    ArtifactModules -->|"use LAVA funcs"| LavaFuncs
    ArtifactModules -->|"generate data"| ArtifactReport

    %% Report generation
    ArtifactReport -->|"writes reports"| Output

    %% Packaging connections
    CLI -->|"packaged by"| SpecCLI
    GUI -->|"packaged by"| SpecGUI
    CLI -->|"macOS bundle"| SpecCLI_MAC
    GUI -->|"macOS bundle"| SpecGUI_MAC

    %% Dev/Admin & CI connections
    CI1 -->|"runs scripts"| AdminDocs
    CI2 -->|"runs scripts"| AdminDocs
    CI1 -->|"triggers tests"| TestRunner
    TestRunner -->|"uses definitions"| TestCases
    CI1 -->|"updates module info"| ArtifactModules
    CI2 -->|"summarizes files"| FileSeeker

    %% External deps usage
    External --> CLI
    External --> GUI
    External --> FileSeeker

    %% Click Events
    click CLI "https://github.com/abrignoni/ileapp/blob/main/ileapp.py"
    click GUI "https://github.com/abrignoni/ileapp/blob/main/ileappGUI.py"
    click FileSeeker "https://github.com/abrignoni/ileapp/blob/main/scripts/search_files.py"
    click PluginLoader "https://github.com/abrignoni/ileapp/blob/main/scripts/plugin_loader.py"
    click ArtifactModules "https://github.com/abrignoni/ileapp/tree/main/scripts/artifacts/"
    click ILAPFUNCS "https://github.com/abrignoni/ileapp/blob/main/scripts/ilapfuncs.py"
    click FileType "https://github.com/abrignoni/ileapp/blob/main/scripts/filetype.py"
    click Parse3 "https://github.com/abrignoni/ileapp/blob/main/scripts/parse3.py"
    click ChatRender "https://github.com/abrignoni/ileapp/blob/main/scripts/chat_rendering.py"
    click LavaFuncs "https://github.com/abrignoni/ileapp/blob/main/scripts/lavafuncs.py"
    click ArtifactReport "https://github.com/abrignoni/ileapp/blob/main/scripts/artifact_report.py"
    click SpecCLI "https://github.com/abrignoni/ileapp/blob/main/scripts/pyinstaller/ileapp.spec"
    click SpecGUI "https://github.com/abrignoni/ileapp/blob/main/scripts/pyinstaller/ileappGUI.spec"
    click SpecCLI_MAC "https://github.com/abrignoni/ileapp/blob/main/scripts/pyinstaller/ileapp_macOS.spec"
    click SpecGUI_MAC "https://github.com/abrignoni/ileapp/blob/main/scripts/pyinstaller/ileappGUI_macOS.spec"
    click CI1 "https://github.com/abrignoni/ileapp/blob/main/.github/workflows/update_module_info.yml"
    click CI2 "https://github.com/abrignoni/ileapp/blob/main/.github/workflows/filepath_search_summary.yml"
    click AdminDocs "https://github.com/abrignoni/ileapp/tree/main/admin/docs/"
    click TestCases "https://github.com/abrignoni/ileapp/tree/main/admin/test/cases/"
    click TestRunner "https://github.com/abrignoni/ileapp/tree/main/admin/test/scripts/"

    %% Styles
    classDef frontend fill:#B3D4FC,stroke:#0366d6,color:#000;
    classDef core fill:#C8E6C9,stroke:#2E7D32,color:#000;
    classDef plugins fill:#FFCC80,stroke:#EF6C00,color:#000;
    classDef utility fill:#FFF59D,stroke:#F9A825,color:#000;
    classDef output fill:#E1BEE7,stroke:#8E24AA,color:#000;
    classDef packaging fill:#B39DDB,stroke:#6A1B9A,color:#000;
    classDef dev fill:#CFD8DC,stroke:#455A64,color:#000;
    classDef external fill:#ECEFF1,stroke:#90A4AE,color:#000;
```
