# rahimgujjar/whatsapp-wal-xray architecture

> Architecture diagram of the GitHub repository rahimgujjar/whatsapp-wal-xray, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rahimgujjar/whatsapp-wal-xray
- Repository: https://github.com/rahimgujjar/whatsapp-wal-xray

## Overview

WAL-XRay is a command-line client-side forensic suite for examining WhatsApp SQLite WAL data. Its primary workflow accepts a user-supplied WAL and decryption key, parses and decrypts records, maps them to message and media telemetry, and stores extracted records locally. Separate tools support schema discovery, event filtering, privacy sanitization, endpoint and payload inspection, and media carving. The README describes these capabilities, while sampled source confirms only some of their wiring; independent tools are therefore shown as separate workflows where connections are not established.

Main entry points: [`core-engine/wal_forensic_parser.py`](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/core-engine/wal_forensic_parser.py) (WAL parser), [`diagnostic-tools/wal_universal_mapper.py`](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_universal_mapper.py) (Schema mapper), [`diagnostic-tools/wal_check_header.py`](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_check_header.py) (Header auditor), [`diagnostic-tools/wal_io_latency_tester.py`](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_io_latency_tester.py) (I/O latency monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Forensic Engine"]
  node_parser["WAL parser"]
  node_records[("Forensic database")]
end

subgraph group_discovery["WAL Discovery"]
  node_mapper["Schema mapper"]
  node_header_check["Header auditor"]
  node_latency["I/O latency monitor"]
end

subgraph group_sanitization["Data Sanitization"]
  node_filter["Event filter<br/>[remove_events.py]"]
  node_cleaner["PII and duplicate cleaner<br/>[log_cleaner.py]"]
  node_pseudonymizer["PII pseudonymizer"]
end

subgraph group_inspection["Telemetry Inspection"]
  node_pattern_finder["Pattern classifier"]
  node_endpoint_scanner["Endpoint scanner<br/>[wal_debug_cols.py]"]
  node_range_auditor["Column auditor"]
  node_thumbnail["Media carver"]
end

node_operator(("Analyst"))
node_wal_input["WAL file"]
node_aes_key["AES key"]
node_telemetry_log["Telemetry log"]
node_hex_payload["Hex payload"]

node_operator -->|"runs with"| node_parser
node_wal_input -->|"reads WAL"| node_parser
node_aes_key -->|"decrypts with"| node_parser
node_parser -->|"writes records"| node_records
node_operator -->|"runs on WAL"| node_mapper
node_wal_input -->|"maps structure"| node_mapper
node_operator -->|"checks WAL"| node_header_check
node_wal_input -->|"reads header"| node_header_check
node_operator -->|"starts monitor"| node_latency
node_wal_input -->|"measures I/O"| node_latency
node_operator -->|"filters log"| node_filter
node_telemetry_log -->|"reads events"| node_filter
node_operator -->|"cleans log"| node_cleaner
node_telemetry_log -->|"reads events"| node_cleaner
node_operator -->|"pseudonymizes log"| node_pseudonymizer
node_telemetry_log -->|"reads text"| node_pseudonymizer
node_operator -->|"classifies log"| node_pattern_finder
node_telemetry_log -->|"scans entries"| node_pattern_finder
node_operator -->|"inspects log"| node_endpoint_scanner
node_telemetry_log -->|"scans columns"| node_endpoint_scanner
node_operator -->|"audits columns"| node_range_auditor
node_telemetry_log -->|"reads blocks"| node_range_auditor
node_operator -->|"carves payload"| node_thumbnail
node_hex_payload -->|"decodes hex"| node_thumbnail

click node_parser "https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/core-engine/wal_forensic_parser.py"
click node_records "https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/core-engine/wal_forensic_parser.py"
click node_mapper "https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_universal_mapper.py"
click node_header_check "https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_check_header.py"
click node_latency "https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_io_latency_tester.py"
click node_filter "https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/remove_events.py"
click node_cleaner "https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/data-privacy-compliance/log_cleaner.py"
click node_pseudonymizer "https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/data-privacy-compliance/replace_global_pii.py"
click node_pattern_finder "https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_pattern_finder.py"
click node_endpoint_scanner "https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_debug_cols.py"
click node_range_auditor "https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_inspect_col_ranges.py"
click node_thumbnail "https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/thumbnail_extract.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_parser,node_records toneBlue
class node_mapper,node_header_check,node_latency toneAmber
class node_filter,node_cleaner,node_pseudonymizer toneMint
class node_pattern_finder,node_endpoint_scanner,node_range_auditor,node_thumbnail toneRose
class node_operator,node_wal_input,node_aes_key,node_telemetry_log,node_hex_payload toneIndigo
```

## Components

### Forensic Engine

- [WAL parser](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/core-engine/wal_forensic_parser.py): `core-engine/wal_forensic_parser.py`
- [Forensic database](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/core-engine/wal_forensic_parser.py): `core-engine/wal_forensic_parser.py`

### WAL Discovery

- [Schema mapper](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_universal_mapper.py): `diagnostic-tools/wal_universal_mapper.py`
- [Header auditor](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_check_header.py): `diagnostic-tools/wal_check_header.py`
- [I/O latency monitor](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_io_latency_tester.py): `diagnostic-tools/wal_io_latency_tester.py`

### Data Sanitization

- [Event filter](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/remove_events.py): `diagnostic-tools/remove_events.py`
- [PII and duplicate cleaner](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/data-privacy-compliance/log_cleaner.py): `data-privacy-compliance/log_cleaner.py`
- [PII pseudonymizer](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/data-privacy-compliance/replace_global_pii.py): `data-privacy-compliance/replace_global_pii.py`

### Telemetry Inspection

- [Pattern classifier](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_pattern_finder.py): `diagnostic-tools/wal_pattern_finder.py`
- [Endpoint scanner](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_debug_cols.py): `diagnostic-tools/wal_debug_cols.py`
- [Column auditor](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/wal_inspect_col_ranges.py): `diagnostic-tools/wal_inspect_col_ranges.py`
- [Media carver](https://github.com/rahimgujjar/whatsapp-wal-xray/blob/main/diagnostic-tools/thumbnail_extract.py): `diagnostic-tools/thumbnail_extract.py`

### Other components

- **Analyst**
- **WAL file**
- **AES key**
- **Telemetry log**
- **Hex payload**

## Connections

- Analyst → WAL parser: runs with
- WAL file → WAL parser: reads WAL
- AES key → WAL parser: decrypts with
- WAL parser → Forensic database: writes records
- Analyst → Schema mapper: runs on WAL
- WAL file → Schema mapper: maps structure
- Analyst → Header auditor: checks WAL
- WAL file → Header auditor: reads header
- Analyst → I/O latency monitor: starts monitor
- WAL file → I/O latency monitor: measures I/O
- Analyst → Event filter: filters log
- Telemetry log → Event filter: reads events
- Analyst → PII and duplicate cleaner: cleans log
- Telemetry log → PII and duplicate cleaner: reads events
- Analyst → PII pseudonymizer: pseudonymizes log
- Telemetry log → PII pseudonymizer: reads text
- Analyst → Pattern classifier: classifies log
- Telemetry log → Pattern classifier: scans entries
- Analyst → Endpoint scanner: inspects log
- Telemetry log → Endpoint scanner: scans columns
- Analyst → Column auditor: audits columns
- Telemetry log → Column auditor: reads blocks
- Analyst → Media carver: carves payload
- Hex payload → Media carver: decodes hex