# sjasonp/historylibhelper architecture

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

- Interactive diagram: https://gitdiagram.com/sjasonp/historylibhelper
- Repository: https://github.com/sjasonp/historylibhelper

## Overview

HistoryLib Helper is a local-only browser-history exporter, with both a Wails desktop interface and a CLI. The main workflow discovers browser profiles, reads their history from a consistent private SQLite snapshot, combines and sorts records, then writes a HistoryLib .hlz archive with time indexes and optional password protection. The CLI also accepts manually selected database paths. The reader implementation was not sampled, so snapshot and database-reading details rely on the README; internal wiring beyond the sampled calls is not inferred.

Main entry points: [`internal/service/service.go`](https://github.com/sjasonp/historylibhelper/blob/main/internal/service/service.go) (Export service), [`app.go`](https://github.com/sjasonp/historylibhelper/blob/main/app.go) (App methods), [`cmd/hlz-export/main.go`](https://github.com/sjasonp/historylibhelper/blob/main/cmd/hlz-export/main.go) (Export CLI), [`internal/hlz/export.go`](https://github.com/sjasonp/historylibhelper/blob/main/internal/hlz/export.go) (HLZ archive writer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_frontend["Desktop interface<br/>[App.tsx]"]
  node_wails_bridge["Wails bindings<br/>[App.js]"]
  node_app["App methods<br/>[app.go]"]
  node_cli["Export CLI<br/>[main.go]"]
  node_save_dialog["Save-file dialog<br/>[app.go]"]
end

subgraph group_browser["Browser sources"]
  node_discovery["Profile discovery<br/>[discovery.go]"]
  node_manual_profile["Manual profile<br/>[discovery.go]"]
  node_reader["History reader<br/>[reader.go]"]
  node_source_db[("Browser history DB")]
  node_snapshot[("Private DB snapshot<br/>[reader.go]")]
end

subgraph group_processing["Export processing"]
  node_service["Export service<br/>[service.go]"]
  node_records["History records<br/>[model.go]"]
end

subgraph group_archive["Archive output"]
  node_hlz_export["HLZ archive writer<br/>[export.go]"]
  node_indexes["Time indexes<br/>[export.go]"]
  node_encrypt["Archive encryption<br/>[encrypt.go]"]
  node_output["HLZ file"]
end

node_desktop_user(("Desktop user"))
node_cli_user(("CLI user"))

node_desktop_user -->|"uses"| node_frontend
node_frontend -->|"invokes"| node_wails_bridge
node_wails_bridge -->|"dispatches"| node_app
node_app -->|"opens"| node_save_dialog
node_save_dialog -->|"returns path"| node_frontend
node_cli_user -->|"runs"| node_cli
node_frontend -->|"requests discovery"| node_app
node_app -->|"discovers profiles"| node_service
node_cli -->|"discovers profiles"| node_service
node_service -->|"discovers"| node_discovery
node_cli -->|"constructs profile"| node_manual_profile
node_source_db -->|"read-only access"| node_reader
node_reader -->|"creates snapshot"| node_snapshot
node_service -->|"reads history"| node_reader
node_reader -->|"returns records"| node_records
node_service -->|"exports records"| node_hlz_export
node_hlz_export -->|"writes indexes"| node_indexes
node_hlz_export -.->|"encrypts optionally"| node_encrypt
node_hlz_export -->|"writes archive"| node_output
node_app -->|"exports profiles"| node_service
node_cli -->|"exports profiles"| node_service
node_service -->|"combines and sorts"| node_records

click node_frontend "https://github.com/sjasonp/historylibhelper/blob/main/frontend/src/App.tsx"
click node_wails_bridge "https://github.com/sjasonp/historylibhelper/blob/main/frontend/wailsjs/go/main/App.js"
click node_app "https://github.com/sjasonp/historylibhelper/blob/main/app.go"
click node_cli "https://github.com/sjasonp/historylibhelper/blob/main/cmd/hlz-export/main.go"
click node_service "https://github.com/sjasonp/historylibhelper/blob/main/internal/service/service.go"
click node_discovery "https://github.com/sjasonp/historylibhelper/blob/main/internal/browser/discovery.go"
click node_manual_profile "https://github.com/sjasonp/historylibhelper/blob/main/internal/browser/discovery.go"
click node_reader "https://github.com/sjasonp/historylibhelper/blob/main/internal/browser/reader.go"
click node_snapshot "https://github.com/sjasonp/historylibhelper/blob/main/internal/browser/reader.go"
click node_records "https://github.com/sjasonp/historylibhelper/blob/main/internal/model/model.go"
click node_hlz_export "https://github.com/sjasonp/historylibhelper/blob/main/internal/hlz/export.go"
click node_indexes "https://github.com/sjasonp/historylibhelper/blob/main/internal/hlz/export.go"
click node_encrypt "https://github.com/sjasonp/historylibhelper/blob/main/internal/hlz/encrypt.go"
click node_save_dialog "https://github.com/sjasonp/historylibhelper/blob/main/app.go"

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_frontend,node_wails_bridge,node_app,node_cli,node_save_dialog,node_desktop_user,node_cli_user toneBlue
class node_discovery,node_manual_profile,node_reader,node_source_db,node_snapshot toneAmber
class node_service,node_records toneMint
class node_hlz_export,node_indexes,node_encrypt,node_output toneRose
```

## Components

### User interfaces

- [Desktop interface](https://github.com/sjasonp/historylibhelper/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Wails bindings](https://github.com/sjasonp/historylibhelper/blob/main/frontend/wailsjs/go/main/App.js): `frontend/wailsjs/go/main/App.js`
- [App methods](https://github.com/sjasonp/historylibhelper/blob/main/app.go): `app.go`
- [Export CLI](https://github.com/sjasonp/historylibhelper/blob/main/cmd/hlz-export/main.go): `cmd/hlz-export/main.go`
- [Save-file dialog](https://github.com/sjasonp/historylibhelper/blob/main/app.go): `app.go`

### Browser sources

- [Profile discovery](https://github.com/sjasonp/historylibhelper/blob/main/internal/browser/discovery.go): `internal/browser/discovery.go`
- [Manual profile](https://github.com/sjasonp/historylibhelper/blob/main/internal/browser/discovery.go): `internal/browser/discovery.go`
- [History reader](https://github.com/sjasonp/historylibhelper/blob/main/internal/browser/reader.go): `internal/browser/reader.go`
- **Browser history DB**
- [Private DB snapshot](https://github.com/sjasonp/historylibhelper/blob/main/internal/browser/reader.go): `internal/browser/reader.go`

### Export processing

- [Export service](https://github.com/sjasonp/historylibhelper/blob/main/internal/service/service.go): `internal/service/service.go`
- [History records](https://github.com/sjasonp/historylibhelper/blob/main/internal/model/model.go): `internal/model/model.go`

### Archive output

- [HLZ archive writer](https://github.com/sjasonp/historylibhelper/blob/main/internal/hlz/export.go): `internal/hlz/export.go`
- [Time indexes](https://github.com/sjasonp/historylibhelper/blob/main/internal/hlz/export.go): `internal/hlz/export.go`
- [Archive encryption](https://github.com/sjasonp/historylibhelper/blob/main/internal/hlz/encrypt.go): `internal/hlz/encrypt.go`
- **HLZ file**

### Other components

- **Desktop user**
- **CLI user**

## Connections

- Desktop user → Desktop interface: uses
- Desktop interface → Wails bindings: invokes
- Wails bindings → App methods: dispatches
- App methods → Save-file dialog: opens
- Save-file dialog → Desktop interface: returns path
- CLI user → Export CLI: runs
- Desktop interface → App methods: requests discovery
- App methods → Export service: discovers profiles
- Export CLI → Export service: discovers profiles
- Export service → Profile discovery: discovers
- Export CLI → Manual profile: constructs profile
- Browser history DB → History reader: read-only access
- History reader → Private DB snapshot: creates snapshot
- Export service → History reader: reads history
- History reader → History records: returns records
- Export service → HLZ archive writer: exports records
- HLZ archive writer → Time indexes: writes indexes
- HLZ archive writer → Archive encryption: encrypts optionally
- HLZ archive writer → HLZ file: writes archive
- App methods → Export service: exports profiles
- Export CLI → Export service: exports profiles
- Export service → History records: combines and sorts