# badoo/hprof-tools architecture

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

- Interactive diagram: https://gitdiagram.com/badoo/hprof-tools
- Repository: https://github.com/badoo/hprof-tools

## Overview

Badoo HPROF Tools is a suite for inspecting, validating, transforming, and analyzing Java/Android heap dumps. Its main conversion path reads HPROF records, crunches them into compact BMD (with some data loss), and can reconstruct HPROF from BMD, optionally recovering strings from application archives. Separate workflows validate dumps, deobfuscate names using ProGuard/DexGuard mappings, and visualize Android-specific data such as view hierarchies and activity intents. The Android example captures dumps and invokes crunching on-device. Some module connections are documented in the README but their full implementations were not sampled.

Main entry points: [`hprof-viewer/src/main/java/com/badoo/hprof/viewer/HprofViewer.java`](https://github.com/badoo/hprof-tools/blob/master/hprof-viewer/src/main/java/com/badoo/hprof/viewer/HprofViewer.java) (HPROF viewer), [`deobfuscator/src/main/java/com/badoo/hprof/deobfuscator/HprofDeobfuscator.java`](https://github.com/badoo/hprof-tools/blob/master/deobfuscator/src/main/java/com/badoo/hprof/deobfuscator/HprofDeobfuscator.java) (Dump deobfuscator), [`cruncher/src/main/java/com/badoo/hprof/cruncher/HprofCruncher.java`](https://github.com/badoo/hprof-tools/blob/master/cruncher/src/main/java/com/badoo/hprof/cruncher/HprofCruncher.java) (HPROF cruncher), [`decruncher/src/main/java/com/badoo/bmd/decruncher/BmdDecruncher.java`](https://github.com/badoo/hprof-tools/blob/master/decruncher/src/main/java/com/badoo/bmd/decruncher/BmdDecruncher.java) (BMD decruncher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_format["Heap formats"]
  node_hprofreader["HPROF reader<br/>[HprofReader.java]"]
  node_hprofwriter["HPROF writer<br/>[HprofWriter.java]"]
  node_bmdreader["BMD reader<br/>[BmdReader.java]"]
  node_bmdwriter["BMD writer<br/>[DataWriter.java]"]
end

subgraph group_convert["Format conversion"]
  node_crunch["HPROF cruncher<br/>[HprofCruncher.java]"]
  node_crunchprocessor["Crunch processor"]
  node_decrunch["BMD decruncher<br/>[BmdDecruncher.java]"]
  node_decrunchprocessor["Decrunch processor"]
  node_stringreaders["Archive string readers"]
end

subgraph group_inspect["Dump analysis"]
  node_validator["Dump validator"]
  node_validatingprocessor["Validation checks"]
  node_deobfuscator["Dump deobfuscator"]
  node_mappingreader["Mapping model<br/>[Mapping.java]"]
  node_viewer["HPROF viewer<br/>[HprofViewer.java]"]
  node_viewdata["Dump data model"]
  node_androidmodels["Android view models"]
  node_viewerui["Viewer UI"]
end

subgraph group_android["Android capture"]
  node_activity["Example app<br/>[MainActivity.java]"]
  node_catcher["Dump catcher<br/>[HprofCatcher.java]"]
  node_service["Crunch service"]
end

node_analyst(("Engineer"))
node_hprof["HPROF dump"]
node_bmdfile["BMD file"]
node_mapping["Obfuscation mapping"]
node_apparchive["App archive"]

node_analyst -->|"runs conversion"| node_crunch
node_hprof -->|"input dump"| node_crunch
node_crunch -->|"reads records"| node_hprofreader
node_crunch -->|"processes records"| node_crunchprocessor
node_crunchprocessor -->|"writes BMD"| node_bmdwriter
node_bmdwriter -->|"produces"| node_bmdfile
node_analyst -->|"runs reconstruction"| node_decrunch
node_bmdfile -->|"input format"| node_decrunch
node_decrunch -->|"reads records"| node_bmdreader
node_decrunch -->|"processes records"| node_decrunchprocessor
node_decrunchprocessor -->|"writes HPROF"| node_hprofwriter
node_hprofwriter -->|"produces"| node_hprof
node_decrunchprocessor -.->|"recovers strings"| node_stringreaders
node_apparchive -.->|"supplies strings"| node_stringreaders
node_analyst -->|"runs validation"| node_validator
node_hprof -->|"input dump"| node_validator
node_validator -->|"reads records"| node_hprofreader
node_validator -->|"checks data"| node_validatingprocessor
node_analyst -->|"runs name recovery"| node_deobfuscator
node_hprof -->|"input dump"| node_deobfuscator
node_mapping -->|"mapping input"| node_deobfuscator
node_deobfuscator -->|"uses mappings"| node_mappingreader
node_deobfuscator -->|"reads dump"| node_hprofreader
node_deobfuscator -->|"writes result"| node_hprofwriter
node_analyst -->|"opens dump"| node_viewer
node_hprof -->|"input dump"| node_viewer
node_viewer -->|"reads records"| node_hprofreader
node_viewer -->|"collects dump data"| node_viewdata
node_viewer -->|"builds Android views"| node_androidmodels
node_viewer -->|"renders analysis"| node_viewerui
node_activity -->|"initializes capture"| node_catcher
node_activity -->|"receives status"| node_service
node_service -->|"crunches dump"| node_crunch

click node_hprofreader "https://github.com/badoo/hprof-tools/blob/master/hprof-lib/src/main/java/com/badoo/hprof/library/HprofReader.java"
click node_hprofwriter "https://github.com/badoo/hprof-tools/blob/master/hprof-lib/src/main/java/com/badoo/hprof/library/HprofWriter.java"
click node_bmdreader "https://github.com/badoo/hprof-tools/blob/master/bmd-lib/src/main/java/com/badoo/bmd/BmdReader.java"
click node_bmdwriter "https://github.com/badoo/hprof-tools/blob/master/bmd-lib/src/main/java/com/badoo/bmd/DataWriter.java"
click node_crunch "https://github.com/badoo/hprof-tools/blob/master/cruncher/src/main/java/com/badoo/hprof/cruncher/HprofCruncher.java"
click node_crunchprocessor "https://github.com/badoo/hprof-tools/blob/master/cruncher/src/main/java/com/badoo/hprof/cruncher/CrunchProcessor.java"
click node_decrunch "https://github.com/badoo/hprof-tools/blob/master/decruncher/src/main/java/com/badoo/bmd/decruncher/BmdDecruncher.java"
click node_decrunchprocessor "https://github.com/badoo/hprof-tools/blob/master/decruncher/src/main/java/com/badoo/bmd/decruncher/DecrunchProcessor.java"
click node_stringreaders "https://github.com/badoo/hprof-tools/tree/master/decruncher/src/main/java/com/badoo/bmd/decruncher"
click node_validator "https://github.com/badoo/hprof-tools/blob/master/hprof-validator/src/main/java/com/badoo/hprof/validator/HprofValidator.java"
click node_validatingprocessor "https://github.com/badoo/hprof-tools/blob/master/hprof-validator/src/main/java/com/badoo/hprof/validator/ValidatingProcessor.java"
click node_deobfuscator "https://github.com/badoo/hprof-tools/blob/master/deobfuscator/src/main/java/com/badoo/hprof/deobfuscator/HprofDeobfuscator.java"
click node_mappingreader "https://github.com/badoo/hprof-tools/blob/master/deobfuscator/src/main/java/com/badoo/hprof/deobfuscator/Mapping.java"
click node_viewer "https://github.com/badoo/hprof-tools/blob/master/hprof-viewer/src/main/java/com/badoo/hprof/viewer/HprofViewer.java"
click node_viewdata "https://github.com/badoo/hprof-tools/blob/master/hprof-viewer/src/main/java/com/badoo/hprof/viewer/ViewDataProcessor.java"
click node_androidmodels "https://github.com/badoo/hprof-tools/tree/master/hprof-viewer/src/main/java/com/badoo/hprof/viewer/android"
click node_viewerui "https://github.com/badoo/hprof-tools/tree/master/hprof-viewer/src/main/java/com/badoo/hprof/viewer/ui"
click node_activity "https://github.com/badoo/hprof-tools/blob/master/Android%20example/app/src/main/java/com/badoo/hprof/cruncher/MainActivity.java"
click node_catcher "https://github.com/badoo/hprof-tools/blob/master/Android%20example/cruncher-lib/src/main/java/com/badoo/hprof/cruncher/library/HprofCatcher.java"
click node_service "https://github.com/badoo/hprof-tools/blob/master/Android%20example/cruncher-lib/src/main/java/com/badoo/hprof/cruncher/library/CruncherService.java"

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_hprofreader,node_hprofwriter,node_bmdreader,node_bmdwriter toneBlue
class node_crunch,node_crunchprocessor,node_decrunch,node_decrunchprocessor,node_stringreaders toneAmber
class node_validator,node_validatingprocessor,node_deobfuscator,node_mappingreader,node_viewer,node_viewdata,node_androidmodels,node_viewerui toneMint
class node_activity,node_catcher,node_service toneRose
class node_analyst,node_hprof,node_bmdfile,node_mapping,node_apparchive toneIndigo
```

## Components

### Heap formats

- [HPROF reader](https://github.com/badoo/hprof-tools/blob/master/hprof-lib/src/main/java/com/badoo/hprof/library/HprofReader.java): `hprof-lib/src/main/java/com/badoo/hprof/library/HprofReader.java`
- [HPROF writer](https://github.com/badoo/hprof-tools/blob/master/hprof-lib/src/main/java/com/badoo/hprof/library/HprofWriter.java): `hprof-lib/src/main/java/com/badoo/hprof/library/HprofWriter.java`
- [BMD reader](https://github.com/badoo/hprof-tools/blob/master/bmd-lib/src/main/java/com/badoo/bmd/BmdReader.java): `bmd-lib/src/main/java/com/badoo/bmd/BmdReader.java`
- [BMD writer](https://github.com/badoo/hprof-tools/blob/master/bmd-lib/src/main/java/com/badoo/bmd/DataWriter.java): `bmd-lib/src/main/java/com/badoo/bmd/DataWriter.java`

### Format conversion

- [HPROF cruncher](https://github.com/badoo/hprof-tools/blob/master/cruncher/src/main/java/com/badoo/hprof/cruncher/HprofCruncher.java): `cruncher/src/main/java/com/badoo/hprof/cruncher/HprofCruncher.java`
- [Crunch processor](https://github.com/badoo/hprof-tools/blob/master/cruncher/src/main/java/com/badoo/hprof/cruncher/CrunchProcessor.java): `cruncher/src/main/java/com/badoo/hprof/cruncher/CrunchProcessor.java`
- [BMD decruncher](https://github.com/badoo/hprof-tools/blob/master/decruncher/src/main/java/com/badoo/bmd/decruncher/BmdDecruncher.java): `decruncher/src/main/java/com/badoo/bmd/decruncher/BmdDecruncher.java`
- [Decrunch processor](https://github.com/badoo/hprof-tools/blob/master/decruncher/src/main/java/com/badoo/bmd/decruncher/DecrunchProcessor.java): `decruncher/src/main/java/com/badoo/bmd/decruncher/DecrunchProcessor.java`
- [Archive string readers](https://github.com/badoo/hprof-tools/tree/master/decruncher/src/main/java/com/badoo/bmd/decruncher): `decruncher/src/main/java/com/badoo/bmd/decruncher`

### Dump analysis

- [Dump validator](https://github.com/badoo/hprof-tools/blob/master/hprof-validator/src/main/java/com/badoo/hprof/validator/HprofValidator.java): `hprof-validator/src/main/java/com/badoo/hprof/validator/HprofValidator.java`
- [Validation checks](https://github.com/badoo/hprof-tools/blob/master/hprof-validator/src/main/java/com/badoo/hprof/validator/ValidatingProcessor.java): `hprof-validator/src/main/java/com/badoo/hprof/validator/ValidatingProcessor.java`
- [Dump deobfuscator](https://github.com/badoo/hprof-tools/blob/master/deobfuscator/src/main/java/com/badoo/hprof/deobfuscator/HprofDeobfuscator.java): `deobfuscator/src/main/java/com/badoo/hprof/deobfuscator/HprofDeobfuscator.java`
- [Mapping model](https://github.com/badoo/hprof-tools/blob/master/deobfuscator/src/main/java/com/badoo/hprof/deobfuscator/Mapping.java): `deobfuscator/src/main/java/com/badoo/hprof/deobfuscator/Mapping.java`
- [HPROF viewer](https://github.com/badoo/hprof-tools/blob/master/hprof-viewer/src/main/java/com/badoo/hprof/viewer/HprofViewer.java): `hprof-viewer/src/main/java/com/badoo/hprof/viewer/HprofViewer.java`
- [Dump data model](https://github.com/badoo/hprof-tools/blob/master/hprof-viewer/src/main/java/com/badoo/hprof/viewer/ViewDataProcessor.java): `hprof-viewer/src/main/java/com/badoo/hprof/viewer/ViewDataProcessor.java`
- [Android view models](https://github.com/badoo/hprof-tools/tree/master/hprof-viewer/src/main/java/com/badoo/hprof/viewer/android): `hprof-viewer/src/main/java/com/badoo/hprof/viewer/android`
- [Viewer UI](https://github.com/badoo/hprof-tools/tree/master/hprof-viewer/src/main/java/com/badoo/hprof/viewer/ui): `hprof-viewer/src/main/java/com/badoo/hprof/viewer/ui`

### Android capture

- [Example app](https://github.com/badoo/hprof-tools/blob/master/Android%20example/app/src/main/java/com/badoo/hprof/cruncher/MainActivity.java): `Android example/app/src/main/java/com/badoo/hprof/cruncher/MainActivity.java`
- [Dump catcher](https://github.com/badoo/hprof-tools/blob/master/Android%20example/cruncher-lib/src/main/java/com/badoo/hprof/cruncher/library/HprofCatcher.java): `Android example/cruncher-lib/src/main/java/com/badoo/hprof/cruncher/library/HprofCatcher.java`
- [Crunch service](https://github.com/badoo/hprof-tools/blob/master/Android%20example/cruncher-lib/src/main/java/com/badoo/hprof/cruncher/library/CruncherService.java): `Android example/cruncher-lib/src/main/java/com/badoo/hprof/cruncher/library/CruncherService.java`

### Other components

- **Engineer**
- **HPROF dump**
- **BMD file**
- **Obfuscation mapping**
- **App archive**

## Connections

- Engineer → HPROF cruncher: runs conversion
- HPROF dump → HPROF cruncher: input dump
- HPROF cruncher → HPROF reader: reads records
- HPROF cruncher → Crunch processor: processes records
- Crunch processor → BMD writer: writes BMD
- BMD writer → BMD file: produces
- Engineer → BMD decruncher: runs reconstruction
- BMD file → BMD decruncher: input format
- BMD decruncher → BMD reader: reads records
- BMD decruncher → Decrunch processor: processes records
- Decrunch processor → HPROF writer: writes HPROF
- HPROF writer → HPROF dump: produces
- Decrunch processor → Archive string readers: recovers strings
- App archive → Archive string readers: supplies strings
- Engineer → Dump validator: runs validation
- HPROF dump → Dump validator: input dump
- Dump validator → HPROF reader: reads records
- Dump validator → Validation checks: checks data
- Engineer → Dump deobfuscator: runs name recovery
- HPROF dump → Dump deobfuscator: input dump
- Obfuscation mapping → Dump deobfuscator: mapping input
- Dump deobfuscator → Mapping model: uses mappings
- Dump deobfuscator → HPROF reader: reads dump
- Dump deobfuscator → HPROF writer: writes result
- Engineer → HPROF viewer: opens dump
- HPROF dump → HPROF viewer: input dump
- HPROF viewer → HPROF reader: reads records
- HPROF viewer → Dump data model: collects dump data
- HPROF viewer → Android view models: builds Android views
- HPROF viewer → Viewer UI: renders analysis
- Example app → Dump catcher: initializes capture
- Example app → Crunch service: receives status
- Crunch service → HPROF cruncher: crunches dump