# bepaald/signalbackup-tools architecture

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

- Interactive diagram: https://gitdiagram.com/bepaald/signalbackup-tools
- Repository: https://github.com/bepaald/signalbackup-tools

## Overview

##### Project Type and Purpose
- This is a single‐binary C++17 command-line application (“signalbackup-tools”) for decrypting, inspecting, modifying and re-encrypting Signal Android backup files. It uses OpenSSL for crypto, SQLite3 for database operations, and (optionally) D-Bus to fetch Signal Desktop keys.

##### High-Level File-Structure Analysis
- Top-level build/config: CMakeLists.txt, BUILDSCRIPT.bash, .github/workflows
- CLI/front-end: main.cc, main.h, arg/ (argument parsing)
- Crypto layer: cryptbase/, sqlcipherdecryptor/
- Frame modules: headerframe/, databaseversionframe/, attachmentframe/, avatarframe/, stickerframe/, keyvalueframe/, sharedprefframe/, sqlstatementframe/, endframe/
- I/O layer: androidattachmentreader/, desktopattachmentreader/, rawfileattachmentreader/, baseattachmentreader/
- Database layer: filesqlitedb/, memfiledb/, memsqlitedb/, jsondatabase/
- Operation modules: signalbackup/ (dump, export, crop, merge, import), csvreader/, xmldocument/
- Utility modules: base64/, protobufparser/, common_*.h, logger/, scopeguard/, etc.

##### Key Insights from README
- The tool reads an encrypted backup file (or directory), decrypts it frame by frame, reconstructs an in-memory SQLite DB, performs user-requested operations (dump, export, fix, merge, import), then writes out frames and re-encrypts into a new backup.
- Supports multiple export formats (HTML, TXT, CSV, XML), plus import from Signal Desktop and Telegram JSON.

##### Main Components
a. CLI Front-End
- main.cc + arg module
- Parses flags and subcommands (dump, exporthtml, importfromdesktop, etc.)
b. Crypto Layer
- cryptbase: key derivation (PBKDF2), cipher/MAC setup
- sqlcipherdecryptor: decrypt SQLite-encrypted Desktop DB
- fileencryptor/filedecryptor: frame-level encrypt/decrypt
c. Frame Parser/Writer Pipeline
- Sequence of Frame modules (HeaderFrame → DatabaseVersionFrame → SqlStatementFrame → SharedPrefFrame → KeyValueFrame → AttachmentFrame/AvatarFrame/StickerFrame → EndFrame)
- Each module reads/writes its SBF binary frame; collectively they reconstruct or assemble backup.
d. In-Memory Database
- filesqlitedb / memfiledb / memsqlitedb for temporary DB
- JSONDatabase for JSON import/export
e. I/O Readers/Writers
- AndroidAttachmentReader, DesktopAttachmentReader, RawFileAttachmentReader for pulling attachment bytes from backups or directories
f. Operation Engines
- signalbackup/: core logic for dumping, cropping, merging, fix-corruption
- Export modules: csvreader, xmldocument, HTML template engine (within signalbackup/)
- Import modules: desktopdatabase (DBus or manual key), JSON import, Telegram mapping
g. External Dependencies
- OpenSSL (crypto)
- SQLite3 (database engine)
- D-Bus (optional, to fetch desktop secrets)
- File system (reading/writing backups and directories)

##### Relationships & Data Flows
- Branch:
- Database → Operation Engines (dump to FS, crop, fix, merge) → Frame Writer → Crypto Layer → New backup file
- Database → Export Engines (HTML/TXT/CSV/XML) → Output directory/files
- External Input (Desktop DB / JSON) → Import Engines → In-Memory Database
- External Dependencies called by respective layers (OpenSSL by Crypto, SQLite by DB layer, D-Bus by desktopdatabase).

##### Architectural Patterns & Principles
- Modular layering: separation of concerns between CLI, crypto, parsing/writing, DB, operations, I/O, export/import
- Pipeline pattern: sequential frame processing
- Strategy/Plugin style: each frame type and each operation (dump, export, import) lives in its own module
- Single executable “monolith” with clear internal modules rather than microservices

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Front-End"
        direction TB
        CLI_Main["main.cc"]:::core
        ArgParser["arg/"]:::core
    end

    %% Crypto Layer
    subgraph "Crypto Layer"
        direction TB
        CryptBase["cryptbase/"]:::core
        SQLCipherDecryptor["sqlcipherdecryptor/"]:::core
        FileDecryptor["filedecryptor/"]:::core
        FileEncryptor["fileencryptor/"]:::core
    end

    %% Frame Parser Pipeline
    subgraph "Frame Parser Pipeline"
        direction TB
        HeaderFrame["headerframe/"]:::core
        DatabaseVersionFrame["databaseversionframe/"]:::core
        SqlStatementFrame["sqlstatementframe/"]:::core
        SharedPrefFrame["sharedprefframe/"]:::core
        KeyValueFrame["keyvalueframe/"]:::core
        AttachmentFrame["attachmentframe/"]:::core
        AvatarFrame["avatarframe/"]:::core
        StickerFrame["stickerframe/"]:::core
        EndFrame["endframe/"]:::core
    end

    %% In-Memory Database
    subgraph "In-Memory Database"
        direction TB
        FileSqliteDB["filesqlitedb/"]:::db
        MemFileDB["memfiledb/"]:::db
        MemSqliteDB["memsqlitedb/"]:::db
        JsonDatabase["jsondatabase/"]:::db
    end

    %% Operation Engines
    subgraph "Operation Engines"
        direction TB
        SignalBackupCore["signalbackup/"]:::operation
        CSVReader["csvreader/"]:::operation
        XMLDocument["xmldocument/"]:::operation
    end

    %% I/O Readers
    subgraph "I/O Readers"
        direction TB
        AndroidAttachmentReader["androidattachmentreader/"]:::io
        DesktopAttachmentReader["desktopattachmentreader/"]:::io
        RawFileAttachmentReader["rawfileattachmentreader/"]:::io
        BaseAttachmentReader["baseattachmentreader/"]:::io
    end

    %% Export/Import Modules
    subgraph "Export/Import"
        direction TB
        CSVExport["exportcsv (in signalbackup/)"]:::operation
        XMLExport["exportxml (in signalbackup/)"]:::operation
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        OpenSSL["OpenSSL"]:::external
        SQLite3["SQLite3"]:::external
        DBus["D-Bus"]:::external
        FileSystem["File System"]:::external
    end

    %% Connections
    CLI_Main -->|parses flags| ArgParser
    ArgParser -->|derive keys| CryptBase
    CryptBase -->|decrypt backup| FileDecryptor
    FileDecryptor -->|read frames| HeaderFrame
    HeaderFrame --> DatabaseVersionFrame
    DatabaseVersionFrame --> SqlStatementFrame
    SqlStatementFrame --> SharedPrefFrame
    SharedPrefFrame --> KeyValueFrame
    KeyValueFrame --> AttachmentFrame
    AttachmentFrame --> AvatarFrame
    AvatarFrame --> StickerFrame
    StickerFrame --> EndFrame
    EndFrame -->|executeSQL| FileSqliteDB
    EndFrame -->|executeSQL| MemFileDB
    EndFrame -->|executeSQL| MemSqliteDB
    EndFrame -->|executeSQL| JsonDatabase

    FileSqliteDB --> SignalBackupCore
    MemFileDB --> SignalBackupCore
    MemSqliteDB --> SignalBackupCore
    JsonDatabase --> SignalBackupCore

    SignalBackupCore --> CSVExport
    SignalBackupCore --> XMLExport

    CSVExport -->|writes files| FileSystem
    XMLExport -->|writes files| FileSystem

    %% I/O Readers flows
    AndroidAttachmentReader --> AttachmentFrame
    DesktopAttachmentReader --> AttachmentFrame
    RawFileAttachmentReader --> AttachmentFrame
    BaseAttachmentReader --> AttachmentFrame

    %% Crypto re-encrypt flow
    SignalBackupCore --> FileEncryptor
    FileEncryptor -->|produce backup| FileSystem

    %% External deps connections
    CryptBase --> OpenSSL
    SQLCipherDecryptor --> SQLite3
    FileDecryptor --> OpenSSL
    FileEncryptor --> OpenSSL
    SignalBackupCore --> DBus

    %% Click Events
    click CLI_Main "https://github.com/bepaald/signalbackup-tools/blob/master/main.cc"
    click ArgParser "https://github.com/bepaald/signalbackup-tools/tree/master/arg/"
    click CryptBase "https://github.com/bepaald/signalbackup-tools/tree/master/cryptbase/"
    click SQLCipherDecryptor "https://github.com/bepaald/signalbackup-tools/tree/master/sqlcipherdecryptor/"
    click FileDecryptor "https://github.com/bepaald/signalbackup-tools/tree/master/filedecryptor/"
    click FileEncryptor "https://github.com/bepaald/signalbackup-tools/tree/master/fileencryptor/"
    click HeaderFrame "https://github.com/bepaald/signalbackup-tools/tree/master/headerframe/"
    click DatabaseVersionFrame "https://github.com/bepaald/signalbackup-tools/tree/master/databaseversionframe/"
    click SqlStatementFrame "https://github.com/bepaald/signalbackup-tools/tree/master/sqlstatementframe/"
    click SharedPrefFrame "https://github.com/bepaald/signalbackup-tools/tree/master/sharedprefframe/"
    click KeyValueFrame "https://github.com/bepaald/signalbackup-tools/tree/master/keyvalueframe/"
    click AttachmentFrame "https://github.com/bepaald/signalbackup-tools/tree/master/attachmentframe/"
    click AvatarFrame "https://github.com/bepaald/signalbackup-tools/tree/master/avatarframe/"
    click StickerFrame "https://github.com/bepaald/signalbackup-tools/tree/master/stickerframe/"
    click EndFrame "https://github.com/bepaald/signalbackup-tools/tree/master/endframe/"
    click FileSqliteDB "https://github.com/bepaald/signalbackup-tools/tree/master/filesqlitedb/"
    click MemFileDB "https://github.com/bepaald/signalbackup-tools/tree/master/memfiledb/"
    click MemSqliteDB "https://github.com/bepaald/signalbackup-tools/tree/master/memsqlitedb/"
    click JsonDatabase "https://github.com/bepaald/signalbackup-tools/tree/master/jsondatabase/"
    click AndroidAttachmentReader "https://github.com/bepaald/signalbackup-tools/tree/master/androidattachmentreader/"
    click DesktopAttachmentReader "https://github.com/bepaald/signalbackup-tools/tree/master/desktopattachmentreader/"
    click RawFileAttachmentReader "https://github.com/bepaald/signalbackup-tools/tree/master/rawfileattachmentreader/"
    click BaseAttachmentReader "https://github.com/bepaald/signalbackup-tools/tree/master/baseattachmentreader/"
    click SignalBackupCore "https://github.com/bepaald/signalbackup-tools/tree/master/signalbackup/"
    click CSVReader "https://github.com/bepaald/signalbackup-tools/tree/master/csvreader/"
    click XMLDocument "https://github.com/bepaald/signalbackup-tools/tree/master/xmldocument/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#1a73e8,color:#000;
    classDef db fill:#daf5d4,stroke:#34a853,color:#000;
    classDef io fill:#d0f0fd,stroke:#00a1f1,color:#000;
    classDef operation fill:#fde7c5,stroke:#fbbc04,color:#000;
    classDef external fill:#e0e0e0,stroke:#a0a0a0,color:#000;
```
