# 0xcgz/exifxtract architecture

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

- Interactive diagram: https://gitdiagram.com/0xcgz/exifxtract
- Repository: https://github.com/0xcgz/exifxtract

## Overview

**ExifXtract** is a **terminal-native, single-node Python CLI tool** for **image forensics + metadata intelligence**. It runs locally, reads image files, extracts/normalizes EXIF (including GPS), optionally calls reverse-geocoding, generates hashes, performs a simple steganography “anomaly” heuristic, can **strip metadata**, and exports **TXT/JSON reports** plus appends to a session **log**.

From the file tree + README, this is **not** a distributed system; the “architecture” is primarily **a local runtime pipeline** with optional external API calls.

**Key evidence from repo:**
- `ExifXtract.py` = the whole application entrypoint and (likely) all logic.
- `requirements.txt` includes `Pillow`, `rich`, optional `geopy`.
- `assets/` contains demo/branding artifacts (not runtime-critical unless referenced by UI).
- Mentions PyInstaller-built `.exe` in README (packaging/distribution concern).

##### Entry & Control Plane
- **CLI Argument Parser (headless mode)**
Handles: `--path`, `--dir`, `--strip`, `--preview`, `--version`.
- **Interactive TUI Menu (default)**
Main menu routing: Deep Analysis / Bulk Scan / Metadata Remover / Thumbnail Preview.

##### Core Forensic Pipeline (Data Plane)
- **File Enumerator**
- Single file selection OR directory traversal (bulk scan).
- Filters by supported formats: JPG/PNG/TIFF/WEBP.
- **Image Loader / Decoder (Pillow)**
- Opens image, reads dimensions, maybe extracts embedded thumbnail.
- **Metadata Extractor (EXIF/IFD/Sub-IFD/GPS-IFD)**
- Parses camera tags, timestamps, software fields, GPS fields.
- **GPS Normalizer**
- Converts raw EXIF GPS to decimal lat/lon.
- Builds **Google Maps** URL.
- **Reverse Geocoder (Optional: geopy)**
- External call to geocoding provider (often Nominatim/OSM via geopy).
- Produces human-readable address.
- **Hashing Engine**
- MD5, SHA1, SHA256 over the file bytes.
- **Stego “Anomaly” Detector (Heuristic)**
- Compares file size vs resolution to flag suspiciously large payloads.
- **Metadata Sanitizer / Stripper**
- Outputs a “clean” copy without EXIF metadata.

##### Output & Audit
- **Report Generator**
- Writes timestamped `.txt` and `.json`.
- Consolidates results for bulk mode.
- **Console Renderer (rich)**
- **Session Logger**
- Appends operations to `exifxtract.log`.

##### Packaging / Distribution (non-runtime, but important context)
- **PyInstaller Build Artifact (mentioned)**
- Not in the tree, but README implies a packaged `.exe`.

##### If GPS exists: GPS Normalizer → lat/lon + maps link
7. If reverse geocoding enabled: **Reverse Geocoder** → **External Geocoding Service** → address

##### Bulk scan
- “File Enumerator” loops over N files and feeds the same pipeline; “Report Generator” consolidates.

##### Architectural patterns & principles to highlight
Even in a small tool, call out the real patterns:

- **Pipeline / staged processing**: enumerate → load → extract → enrich → report.
- **Strategy-like optional enrichment**: reverse geocoding is a feature flag / optional dependency.
- **Separation of concerns** (logical, even if not physically separated): UI vs core analysis vs output.
- **Deterministic artifacts**: reports + hashes used for integrity and reproducibility.
- **Side-effect boundaries**: filesystem writes (reports, stripped image, logs) and network calls (geocoding).

##### “Don’t overthink it”: maximize component separation (even within one file)
- where to refactor (future modularization),
- what can fail (I/O vs decode vs network),
- what’s optional vs required,
- and where evidence/logging is produced for forensics.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1 — System Context (C4 L1)
  %% =========================
  subgraph "System Context (Local, Single-Node CLI Tool)"
    direction TB

    User["Investigator / OSINT Analyst\n(User)"]:::actor

    subgraph "Local Machine (Trust Boundary)"
      direction TB
      ExifXtractSys["ExifXtract (Python CLI App)"]:::system
      FS[("Local Filesystem\n- Input images\n- Output reports\n- exifxtract.log\n- Stripped copies")]:::storage
      Console["Terminal Console\n(rich formatted output)"]:::ui
    end

    Geo["Geocoding Provider\n(Nominatim/OSM etc.)\nvia geopy (Optional)"]:::external
  end

  User -->|"runs"| ExifXtractSys
  FS -->|"reads images"| ExifXtractSys
  ExifXtractSys -->|"writes reports/logs/stripped copies"| FS
  ExifXtractSys -->|"prints results"| Console
  ExifXtractSys <-->|"reverse geocode (optional)"| Geo

  %% =========================
  %% Diagram 2 — Component / Pipeline (Inside one process)
  %% =========================
  subgraph "Component View (Single Python Process: ExifXtract.py)"
    direction TB

    subgraph "Entry & Control Plane"
      direction TB
      CLI["CLI Argument Parser\n(--path/--dir/--strip/--preview/--version)"]:::control
      TUI["Interactive TUI Menu\n(Deep Analysis / Bulk Scan /\nMetadata Remover / Thumbnail Preview)"]:::control
      Router["Main Controller / Router"]:::control
    end

    subgraph "Core Forensic Pipeline (Staged Processing)"
      direction TB
      Enum["File Enumerator\n(single file / directory traversal)\nFilters: JPG/PNG/TIFF/WEBP"]:::pipeline
      Loader["Image Loader / Decoder\n(Pillow)\nDimensions + Thumbnail (Preview)"]:::pipeline
      Extract["Metadata Extractor\n(EXIF/IFD/Sub-IFD/GPS-IFD)"]:::pipeline
      GPSNorm["GPS Normalizer\n(decimal lat/lon + Google Maps link)"]:::pipeline
      RevGeo["Reverse Geocoder\n(geopy) (Optional)"]:::pipelineOpt
      Hash["Hashing Engine\n(MD5 / SHA1 / SHA256)"]:::pipeline
      Stego["Stego 'Anomaly' Heuristic\n(file size vs resolution)"]:::pipeline
      Strip["Metadata Sanitizer / Stripper\n(writes clean copy)"]:::pipelineOpt
    end

    subgraph "Output & Audit"
      direction TB
      Report["Report Generator / Writer\n(TXT + JSON, bulk consolidation)"]:::output
      Logger["Session Logger\n(appends exifxtract.log)"]:::output
      Render["Console Renderer\n(rich colorized categories)"]:::output
    end

    subgraph "Runtime Dependencies"
      direction TB
      Pillow["Pillow\n(Image decode + EXIF access)"]:::dep
      Rich["rich\n(Terminal rendering)"]:::dep
      Geopy["geopy (Optional)\n(Reverse geocoding client)"]:::depOpt
    end
  end

  %% -------- Control plane wiring --------
  User -->|"args"| CLI
  User -->|"interactive"| TUI
  CLI -->|"selects mode"| Router
  TUI -->|"selects mode"| Router

  %% -------- I/O boundaries --------
  FS -->|"ImagePath(s)"| Enum
  Enum -->|"ImagePath"| Loader
  Loader -->|"ImageBytes + Dimensions + Thumbnail?"| Extract
  Extract -->|"MetadataDict"| GPSNorm
  GPSNorm -->|"lat/lon + Maps URL (if GPS)"| Hash
  Extract -->|"Resolution/Metadata"| Stego
  Hash -->|"Hashes"| Stego
  Stego -->|"ForensicResult"| Report
  Report -->|"TXT/JSON artifacts"| FS
  Logger -->|"append log line"| FS
  Render -->|"stdout"| Console

  %% -------- Optional branches --------
  Router -->|"Bulk scan (loop N files)"| Enum
  Router -->|"Deep analysis"| Enum
  Router -->|"Thumbnail preview"| Loader
  Router -->|"Metadata remover"| Strip

  GPSNorm -.->|"if enabled + GPS present"| RevGeo
  RevGeo -.->|"address"| Report
  RevGeo -.->|"address"| Render

  Extract -.->|"if strip requested"| Strip
  Strip -.->|"sanitized copy"| FS

  %% -------- External dependency path (optional) --------
  RevGeo -.->|"request/response (internet)"| Geo

  %% -------- Dependency usage --------
  Loader -->|"uses"| Pillow
  Extract -->|"uses"| Pillow
  Render -->|"uses"| Rich
  RevGeo -.->|"uses (optional)"| Geopy

  %% =========================
  %% Diagram 3 — Packaging / Distribution (Context)
  %% =========================
  subgraph "Packaging / Distribution Context (Non-runtime)"
    direction TB
    Source["Source\n(ExifXtract.py + requirements)"]:::dist
    PyInstaller["PyInstaller\n(build step)"]:::dist
    Exe["Standalone Executable\n(ExifXtract.exe)"]:::distArtifact
    Docs["Docs / Usage / Notes\n(README, CHANGELOG)"]:::docs
    Assets["Demo / Branding Assets"]:::assets
  end

  Source -->|"bundle"| PyInstaller -->|"produces"| Exe
  Docs -->|"describes"| Source
  Assets -->|"ships with (optional)"| Source

  %% =========================
  %% Click Events (from component mapping)
  %% =========================
  click ExifXtractSys "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click CLI "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click TUI "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click Router "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click Enum "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click Loader "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click Extract "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click GPSNorm "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click RevGeo "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click Hash "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click Stego "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click Strip "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click Report "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click Render "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click Logger "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click Pillow "https://github.com/0xcgz/exifxtract/blob/main/requirements.txt"
  click Rich "https://github.com/0xcgz/exifxtract/blob/main/requirements.txt"
  click Geopy "https://github.com/0xcgz/exifxtract/blob/main/requirements.txt"
  click Docs "https://github.com/0xcgz/exifxtract/blob/main/README.md"
  click Source "https://github.com/0xcgz/exifxtract/blob/main/ExifXtract.py"
  click Assets "https://github.com/0xcgz/exifxtract/tree/main/assets/"
  click PyInstaller "https://github.com/0xcgz/exifxtract/blob/main/README.md"
  click Exe "https://github.com/0xcgz/exifxtract/blob/main/README.md"

  %% =========================
  %% Styles (Color-coded)
  %% =========================
  classDef actor fill:#E9F5FF,stroke:#1E6FB9,stroke-width:2,color:#0B2A3A
  classDef system fill:#D6ECFF,stroke:#1E6FB9,stroke-width:2,color:#0B2A3A
  classDef ui fill:#E8F7EE,stroke:#1B8A5A,stroke-width:2,color:#0B2A3A
  classDef storage fill:#F2F2F2,stroke:#666,stroke-width:2,color:#222

  classDef control fill:#DCEBFF,stroke:#2B5DB3,stroke-width:2,color:#0B2A3A
  classDef pipeline fill:#CFE8FF,stroke:#245AA6,stroke-width:2,color:#0B2A3A
  classDef pipelineOpt fill:#CFE8FF,stroke:#245AA6,stroke-width:2,stroke-dasharray:6 4,color:#0B2A3A

  classDef output fill:#DFF7E7,stroke:#1B8A5A,stroke-width:2,color:#0B2A3A
  classDef dep fill:#EFE7FF,stroke:#6A3DB8,stroke-width:2,color:#1C0F33
  classDef depOpt fill:#EFE7FF,stroke:#6A3DB8,stroke-width:2,stroke-dasharray:6 4,color:#1C0F33

  classDef external fill:#FFE7CC,stroke:#C56A00,stroke-width:2,color:#3A2200
  classDef dist fill:#FFF2CC,stroke:#B08900,stroke-width:2,color:#3A2A00
  classDef distArtifact fill:#FFE1A6,stroke:#B08900,stroke-width:2,color:#3A2A00
  classDef docs fill:#FFFFFF,stroke:#444,stroke-width:1,color:#222
  classDef assets fill:#F6F6F6,stroke:#888,stroke-width:1,color:#222
```
