# den4uk/andriller architecture

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

- Interactive diagram: https://gitdiagram.com/den4uk/andriller
- Repository: https://github.com/den4uk/andriller

## Overview

##### Project type and purpose
- Andriller is a desktop forensic utility written in Python that provides both a CLI and a Tkinter‐based GUI.
- Its purpose is to perform read-only data acquisition from Android devices (via ADB or backups), crack lockscreens, decode app databases, take screen captures, and generate HTML/Excel reports.

##### File structure
- Top level:
- andriller-gui.py (entry point for GUI)
- andriller/ (core application package)
- templates/ (Jinja2‐like report templates)
- bin/ (bundled ADB for Windows)
- tests/ (unit tests)
- configuration & packaging files (setup.py, requirements.txt, workflows)
- Inside andriller/:
- __main__.py (CLI entry point)
- adb_conn.py (manages ADB communications)
- driller.py / cracking.py (lockscreen cracking engines)
- decoders.py, decrypts.py, engines.py (data parsing & decryption)
- screencap.py (screen capture logic)
- gui/ (Tkinter windows, dialogs, preferences)
- templates/ (HTML templates for each data type)
- config.py (global settings), utils.py, messages.py, exceptions.py

##### README for additional insights
- Confirms key features: ADB‐based extraction, backup parsing, database decoders, lockscreen cracking, report generation.
- External dependencies: adb CLI tool, python3‐tk.

##### Main components & their interactions
a. User Interface Layer
- CLI Entry Point (andriller CLI via __main__.py)
- GUI Entry Point (andriller-gui.py → andriller.gui.core)
–– invokes Core Controller
b. Core Controller
- orchestrates requests from UI
- loads config, sets up logging
- routes tasks to Subsystems
c. Subsystems
1. ADB Subsystem (adb_conn.py)
– connects to device, issues ADB commands
2. Backup & Filesystem Parser (utils.py + classes.py)
– unpacks .ab backups, tarballs, file trees
3. Decoding Subsystem (decoders.py, decrypts.py, engines.py)
– per-app database parsers (contacts, SMS, WhatsApp)
– crypt file decryption
4. Lockscreen Cracking (driller.py, cracking.py)
– brute-force patterns, PINs, passwords
5. Screen Capture (screencap.py + gui/screen_cap.py)
6. Reporting Engine
– uses templates/REPORT.html and per-data templates via Jinja2‐style rendering
– generates HTML and Excel outputs
d. Configuration & Utilities
- config.py (global parameters)
- messages.py (localized strings)
- exceptions.py (error classes)

##### External dependencies & tools
- adb binary (bundled for Windows, system ADB for Linux/Mac)
- python3‐tk for GUI
- Python standard libraries + listed requirements

##### Architectural patterns & design principles
- Layered architecture: UI → Controller → Subsystems → Data & Templates
- Separation of concerns: decoding, cracking, ADB connection, UI are distinct modules
- Plugin-like decoders: extensible per-app templates and parser classes
- Forensically safe: all operations are read-only

## Diagram (Mermaid)

```mermaid
graph TB
    %% UI Layer
    subgraph "UI Layer"
        CLI_EP["CLI Entry Point\n(__main__.py)\nPython 3.x"]:::ui
        GUI_EP["GUI Entry Point\n(and­riller-gui.py → gui/core.py)\nTkinter"]:::ui
    end

    %% Core Controller Layer
    subgraph "Core Controller"
        CORE["Core Controller\n(engines.py)\nPython 3.x"]:::controller
    end

    %% Subsystem Layer
    subgraph "Subsystems"
        ADB["ADB Subsystem\n(adb_conn.py)\nADB CLI"]:::subsystem
        BACKUP["Backup & Filesystem Parser\n(utils.py, classes.py)\nPython 3.x"]:::subsystem
        DECODING["Decoding Subsystem\n(decoders.py, decrypts.py)\nPython 3.x"]:::subsystem
        CRACKING["Lockscreen Cracking Engine\n(driller.py, cracking.py)\nPython 3.x"]:::subsystem
        SCREEN["Screen Capture\n(screencap.py, gui/screen_cap.py)\nPython 3.x"]:::subsystem
        REPORT["Reporting Engine\n(templates/, statics.py)\nJinja2-style"]:::subsystem
    end

    %% Data & Storage Layer
    subgraph "Data & Storage"
        TEMPLATES["Report Templates\n(templates/)\nJinja2"]:::data
        CONFIG["Config Settings\n(config.py)"]:::data
        MESSAGES["Localization\n(messages.py)"]:::data
        EXCEPTIONS["Error Handling\n(exceptions.py)"]:::data
        TEMPSTORE["Temporary File Store\n(./temp)"]:::data
        OUTPUT["Output Reports\n(HTML, Excel)"]:::data
    end

    %% External Tools
    subgraph "External Tools"
        ADB_BIN["Bundled ADB Binary\n(bin/adb.exe)"]:::external
        PYTK["python3-tk"]:::external
    end

    %% Connections
    CLI_EP -->|"invoke"| CORE
    GUI_EP -->|"invoke"| CORE

    CORE -->|"connect"| ADB
    CORE -->|"parse backup"| BACKUP
    CORE -->|"decode data"| DECODING
    CORE -->|"crack lockscreen"| CRACKING
    CORE -->|"capture screen"| SCREEN
    CORE -->|"render report"| REPORT

    ADB -->|"ADB commands"| ADB_BIN
    BACKUP -->|"file tree"| DECODING
    DECODING -->|"parsed data"| REPORT
    CRACKING -->|"crack results"| REPORT
    SCREEN -->|"screenshots"| REPORT
    REPORT -->|"use templates"| TEMPLATES
    REPORT -->|"produce"| OUTPUT

    CORE -->|"use"| CONFIG
    CORE -->|"use"| MESSAGES
    CORE -->|"use"| EXCEPTIONS

    %% Click Events
    click CLI_EP "https://github.com/den4uk/andriller/blob/master/andriller/__main__.py"
    click GUI_EP "https://github.com/den4uk/andriller/blob/master/andriller-gui.py"
    click CORE "https://github.com/den4uk/andriller/blob/master/andriller/engines.py"
    click ADB "https://github.com/den4uk/andriller/blob/master/andriller/adb_conn.py"
    click BACKUP "https://github.com/den4uk/andriller/blob/master/andriller/utils.py"
    click BACKUP "https://github.com/den4uk/andriller/blob/master/andriller/classes.py"
    click DECODING "https://github.com/den4uk/andriller/blob/master/andriller/decoders.py"
    click DECODING "https://github.com/den4uk/andriller/blob/master/andriller/decrypts.py"
    click CRACKING "https://github.com/den4uk/andriller/blob/master/andriller/driller.py"
    click CRACKING "https://github.com/den4uk/andriller/blob/master/andriller/cracking.py"
    click SCREEN "https://github.com/den4uk/andriller/blob/master/andriller/screencap.py"
    click SCREEN "https://github.com/den4uk/andriller/blob/master/andriller/gui/screen_cap.py"
    click REPORT "https://github.com/den4uk/andriller/tree/master/andriller/templates/"
    click REPORT "https://github.com/den4uk/andriller/blob/master/andriller/statics.py"
    click CONFIG "https://github.com/den4uk/andriller/blob/master/andriller/config.py"
    click MESSAGES "https://github.com/den4uk/andriller/blob/master/andriller/messages.py"
    click EXCEPTIONS "https://github.com/den4uk/andriller/blob/master/andriller/exceptions.py"
    click ADB_BIN "https://github.com/den4uk/andriller/blob/master/andriller/bin/adb.exe"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef controller fill:#90EE90,stroke:#333,stroke-width:1px
    classDef subsystem fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
