# hledgerorg/hledger architecture

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

- Interactive diagram: https://gitdiagram.com/hledgerorg/hledger
- Repository: https://github.com/hledgerorg/hledger

## Overview

hledger is plain-text, multi-currency double-entry accounting software with command-line, terminal and web interfaces. The main workflow is to read a journal or import transaction data, build and check accounting data, then query it for reports or export it. The graph also preserves documented CSV import/export and time-related capabilities. The tree and README establish the overall modules and product scope; sampled source is mainly web-side JavaScript, so detailed Haskell call wiring is not asserted.

Main entry points: [`hledger-lib/Hledger/Read.hs`](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Read.hs) (Input reader), [`hledger-lib/Hledger/Reports.hs`](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Reports.hs) (Report engine), [`hledger-lib/Hledger/Data/Journal.hs`](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Data/Journal.hs) (Journal data), [`hledger/app`](https://github.com/hledgerorg/hledger/tree/main/hledger/app) (Command line)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["Command line"]
  node_terminal["Terminal UI<br/>[hledger-ui.hs]"]
  node_web["Web app<br/>[main.hs]"]
  node_handlers["Web handlers"]
  node_webviews["Web presentation"]
end

subgraph group_input["Input and parsing"]
  node_inputapi["Input reader<br/>[Read.hs]"]
  node_journal["Journal parser<br/>[JournalReader.hs]"]
  node_csv["CSV importer<br/>[CsvReader.hs]"]
  node_rules["Import rules<br/>[RulesReader.hs]"]
  node_timeinput["Time formats<br/>[TimeclockReader.hs]"]
end

subgraph group_engine["Accounting engine"]
  node_journaldata[("Journal data<br/>[Journal.hs]")]
  node_ledgerdata["Ledger model<br/>[Ledger.hs]"]
  node_checks["Journal checks<br/>[JournalChecks.hs]"]
  node_amounts["Amounts and balancing<br/>[Balancing.hs]"]
  node_lots["Lots and valuation<br/>[Lots.hs]"]
  node_query["Query engine<br/>[Query.hs]"]
end

subgraph group_outputs["Reports and output"]
  node_reports["Report engine<br/>[Reports.hs]"]
  node_balance["Balance reports<br/>[BalanceReport.hs]"]
  node_budget["Budget reports<br/>[BudgetReport.hs]"]
  node_register["Register reports"]
  node_writers["Export writers"]
end

node_user(("User"))

node_user -->|"runs commands"| node_cli
node_user -->|"uses"| node_terminal
node_user -->|"opens"| node_web
node_cli -->|"loads data"| node_inputapi
node_terminal -->|"loads data"| node_inputapi
node_web -->|"dispatches"| node_handlers
node_handlers -->|"loads data"| node_inputapi
node_inputapi -->|"parses journals"| node_journal
node_inputapi -->|"imports CSV"| node_csv
node_csv -->|"uses rules"| node_rules
node_inputapi -->|"reads time data"| node_timeinput
node_journal -->|"produces journal"| node_journaldata
node_csv -->|"produces journal"| node_journaldata
node_timeinput -->|"produces journal"| node_journaldata
node_journaldata -->|"checked by"| node_checks
node_journaldata -->|"forms ledger"| node_ledgerdata
node_ledgerdata -->|"balances postings"| node_amounts
node_ledgerdata -->|"tracks lots"| node_lots
node_cli -->|"builds queries"| node_query
node_handlers -->|"builds queries"| node_query
node_query -->|"filters data"| node_reports
node_reports -->|"supports"| node_balance
node_reports -->|"supports"| node_budget
node_reports -->|"supports"| node_register
node_cli -->|"exports data"| node_writers
node_handlers -->|"renders pages"| node_webviews
node_web -->|"serves reports"| node_reports

click node_cli "https://github.com/hledgerorg/hledger/tree/main/hledger/app"
click node_terminal "https://github.com/hledgerorg/hledger/blob/main/hledger-ui/app/hledger-ui.hs"
click node_web "https://github.com/hledgerorg/hledger/blob/main/hledger-web/app/main.hs"
click node_handlers "https://github.com/hledgerorg/hledger/tree/main/hledger-web/Hledger/Web/Handler"
click node_inputapi "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Read.hs"
click node_journal "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Read/JournalReader.hs"
click node_csv "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Read/CsvReader.hs"
click node_rules "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Read/RulesReader.hs"
click node_timeinput "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Read/TimeclockReader.hs"
click node_journaldata "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Data/Journal.hs"
click node_ledgerdata "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Data/Ledger.hs"
click node_checks "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Data/JournalChecks.hs"
click node_amounts "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Data/Balancing.hs"
click node_lots "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Data/Lots.hs"
click node_query "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Query.hs"
click node_reports "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Reports.hs"
click node_balance "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Reports/BalanceReport.hs"
click node_budget "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Reports/BudgetReport.hs"
click node_register "https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Reports/AccountTransactionsReport.hs"
click node_writers "https://github.com/hledgerorg/hledger/tree/main/hledger-lib/Hledger/Write"
click node_webviews "https://github.com/hledgerorg/hledger/tree/main/hledger-web/templates"

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_cli,node_terminal,node_web,node_handlers,node_webviews,node_user toneBlue
class node_inputapi,node_journal,node_csv,node_rules,node_timeinput toneAmber
class node_journaldata,node_ledgerdata,node_checks,node_amounts,node_lots,node_query toneMint
class node_reports,node_balance,node_budget,node_register,node_writers toneRose
```

## Components

### User interfaces

- [Command line](https://github.com/hledgerorg/hledger/tree/main/hledger/app): `hledger/app`
- [Terminal UI](https://github.com/hledgerorg/hledger/blob/main/hledger-ui/app/hledger-ui.hs): `hledger-ui/app/hledger-ui.hs`
- [Web app](https://github.com/hledgerorg/hledger/blob/main/hledger-web/app/main.hs): `hledger-web/app/main.hs`
- [Web handlers](https://github.com/hledgerorg/hledger/tree/main/hledger-web/Hledger/Web/Handler): `hledger-web/Hledger/Web/Handler`
- [Web presentation](https://github.com/hledgerorg/hledger/tree/main/hledger-web/templates): `hledger-web/templates`

### Input and parsing

- [Input reader](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Read.hs): `hledger-lib/Hledger/Read.hs`
- [Journal parser](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Read/JournalReader.hs): `hledger-lib/Hledger/Read/JournalReader.hs`
- [CSV importer](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Read/CsvReader.hs): `hledger-lib/Hledger/Read/CsvReader.hs`
- [Import rules](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Read/RulesReader.hs): `hledger-lib/Hledger/Read/RulesReader.hs`
- [Time formats](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Read/TimeclockReader.hs): `hledger-lib/Hledger/Read/TimeclockReader.hs`

### Accounting engine

- [Journal data](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Data/Journal.hs): `hledger-lib/Hledger/Data/Journal.hs`
- [Ledger model](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Data/Ledger.hs): `hledger-lib/Hledger/Data/Ledger.hs`
- [Journal checks](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Data/JournalChecks.hs): `hledger-lib/Hledger/Data/JournalChecks.hs`
- [Amounts and balancing](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Data/Balancing.hs): `hledger-lib/Hledger/Data/Balancing.hs`
- [Lots and valuation](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Data/Lots.hs): `hledger-lib/Hledger/Data/Lots.hs`
- [Query engine](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Query.hs): `hledger-lib/Hledger/Query.hs`

### Reports and output

- [Report engine](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Reports.hs): `hledger-lib/Hledger/Reports.hs`
- [Balance reports](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Reports/BalanceReport.hs): `hledger-lib/Hledger/Reports/BalanceReport.hs`
- [Budget reports](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Reports/BudgetReport.hs): `hledger-lib/Hledger/Reports/BudgetReport.hs`
- [Register reports](https://github.com/hledgerorg/hledger/blob/main/hledger-lib/Hledger/Reports/AccountTransactionsReport.hs): `hledger-lib/Hledger/Reports/AccountTransactionsReport.hs`
- [Export writers](https://github.com/hledgerorg/hledger/tree/main/hledger-lib/Hledger/Write): `hledger-lib/Hledger/Write`

### Other components

- **User**

## Connections

- User → Command line: runs commands
- User → Terminal UI: uses
- User → Web app: opens
- Command line → Input reader: loads data
- Terminal UI → Input reader: loads data
- Web app → Web handlers: dispatches
- Web handlers → Input reader: loads data
- Input reader → Journal parser: parses journals
- Input reader → CSV importer: imports CSV
- CSV importer → Import rules: uses rules
- Input reader → Time formats: reads time data
- Journal parser → Journal data: produces journal
- CSV importer → Journal data: produces journal
- Time formats → Journal data: produces journal
- Journal data → Journal checks: checked by
- Journal data → Ledger model: forms ledger
- Ledger model → Amounts and balancing: balances postings
- Ledger model → Lots and valuation: tracks lots
- Command line → Query engine: builds queries
- Web handlers → Query engine: builds queries
- Query engine → Report engine: filters data
- Report engine → Balance reports: supports
- Report engine → Budget reports: supports
- Report engine → Register reports: supports
- Command line → Export writers: exports data
- Web handlers → Web presentation: renders pages
- Web app → Report engine: serves reports