# solitarybear/pocketlog architecture

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

- Interactive diagram: https://gitdiagram.com/solitarybear/pocketlog
- Repository: https://github.com/solitarybear/pocketlog

## Overview

PocketLog is an offline desktop app for recording shared expenses and repayments, then showing balances and period reports. The user works through the Qt window and feature pages; those pages call a report/service layer that coordinates participant, expense, settlement and card operations over a local SQLite database. The graph also preserves exact-paise handling, dashboard/report filtering, card repayments, and shared UI presentation. Some feature implementations were not excerpted; their inclusion and limited links rely on README statements and the SOURCE INDEX, not claims of inspecting unsampled code.

Main entry points: [`pocketlog/reports.py`](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/reports.py) (Report service), [`pocketlog/ui/main_window.py`](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/main_window.py) (Navigation window), [`pocketlog/expenses.py`](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/expenses.py) (Expense records), [`pocketlog/db.py`](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/db.py) (SQLite database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop interface"]
  node_app["Application startup<br/>[app.py]"]
  node_window["Navigation window<br/>[main_window.py]"]
  node_expense_ui["Expense editor and list<br/>[expense_dialog.py]"]
  node_settings_ui["People and settings<br/>[settings_page.py]"]
  node_cards_ui["Card activity<br/>[cards_page.py]"]
  node_dashboard_ui["Dashboard<br/>[dashboard_page.py]"]
  node_balances_ui["Balances<br/>[balances_page.py]"]
  node_reports_ui["Reports<br/>[reports_page.py]"]
  node_settlements_ui["Settlements"]
  node_period_ui["Period filter<br/>[period_filter.py]"]
end

subgraph group_domain["Expense domain"]
  node_participant_repo["Participants<br/>[participants.py]"]
  node_expense_repo["Expense records<br/>[expenses.py]"]
  node_settlement_repo["Settlement records<br/>[settlements.py]"]
  node_card_repo["Cards and repayments<br/>[cards.py]"]
  node_models["Domain records<br/>[models.py]"]
  node_money["Exact-paise rules<br/>[money.py]"]
end

subgraph group_analysis["Balances and reporting"]
  node_report_service["Report service<br/>[reports.py]"]
  node_balance_logic["Balance calculation<br/>[balances.py]"]
end

subgraph group_storage["Local data"]
  node_database[("SQLite database<br/>[db.py]")]
  node_config["Data location<br/>[config.py]"]
end

subgraph group_presentation["Shared UI and money"]
  node_widgets["Reusable widgets<br/>[widgets.py]"]
  node_theme["Light and dark themes<br/>[theme.py]"]
end

node_user(("Group member"))

node_user -->|"launches"| node_app
node_app -->|"opens"| node_window
node_app -->|"resolves data path"| node_config
node_app -->|"opens"| node_database
node_window -->|"shows"| node_expense_ui
node_window -->|"shows"| node_settings_ui
node_window -->|"shows"| node_cards_ui
node_window -->|"shows"| node_dashboard_ui
node_window -->|"shows"| node_balances_ui
node_window -->|"shows"| node_reports_ui
node_window -->|"shows"| node_settlements_ui
node_expense_ui -->|"saves expenses"| node_expense_repo
node_settings_ui -->|"manages people"| node_participant_repo
node_cards_ui -->|"records repayments"| node_card_repo
node_dashboard_ui -->|"requests summaries"| node_report_service
node_balances_ui -->|"requests balances"| node_report_service
node_reports_ui -->|"requests reports"| node_report_service
node_settlements_ui -->|"requests settlement data"| node_report_service
node_period_ui -->|"resolves periods"| node_report_service
node_report_service -->|"reads participants"| node_participant_repo
node_report_service -->|"queries expenses"| node_expense_repo
node_report_service -->|"queries settlements"| node_settlement_repo
node_report_service -->|"queries card activity"| node_card_repo
node_report_service -->|"builds balances"| node_balance_logic
node_participant_repo -->|"reads and writes"| node_database
node_expense_repo -->|"reads and writes"| node_database
node_settlement_repo -->|"reads and writes"| node_database
node_card_repo -->|"reads and writes"| node_database
node_expense_repo -->|"validates splits"| node_money
node_expense_ui -->|"computes split"| node_money
node_report_service -->|"builds report records"| node_models
node_expense_repo -->|"returns expense records"| node_models
node_window -->|"uses components"| node_widgets
node_widgets -->|"uses styles"| node_theme

click node_app "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/app.py"
click node_window "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/main_window.py"
click node_expense_ui "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/expense_dialog.py"
click node_settings_ui "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/settings_page.py"
click node_cards_ui "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/cards_page.py"
click node_dashboard_ui "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/dashboard_page.py"
click node_balances_ui "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/balances_page.py"
click node_reports_ui "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/reports_page.py"
click node_settlements_ui "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/settlements_page.py"
click node_period_ui "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/period_filter.py"
click node_report_service "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/reports.py"
click node_participant_repo "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/participants.py"
click node_expense_repo "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/expenses.py"
click node_settlement_repo "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/settlements.py"
click node_card_repo "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/cards.py"
click node_balance_logic "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/balances.py"
click node_models "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/models.py"
click node_money "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/money.py"
click node_database "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/db.py"
click node_config "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/config.py"
click node_widgets "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/widgets.py"
click node_theme "https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/theme.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_app,node_window,node_expense_ui,node_settings_ui,node_cards_ui,node_dashboard_ui,node_balances_ui,node_reports_ui,node_settlements_ui,node_period_ui toneBlue
class node_participant_repo,node_expense_repo,node_settlement_repo,node_card_repo,node_models,node_money toneAmber
class node_report_service,node_balance_logic toneMint
class node_database,node_config toneRose
class node_widgets,node_theme,node_user toneIndigo
```

## Components

### Desktop interface

- [Application startup](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/app.py): `pocketlog/app.py`
- [Navigation window](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/main_window.py): `pocketlog/ui/main_window.py`
- [Expense editor and list](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/expense_dialog.py): `pocketlog/ui/expense_dialog.py`
- [People and settings](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/settings_page.py): `pocketlog/ui/settings_page.py`
- [Card activity](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/cards_page.py): `pocketlog/ui/cards_page.py`
- [Dashboard](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/dashboard_page.py): `pocketlog/ui/dashboard_page.py`
- [Balances](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/balances_page.py): `pocketlog/ui/balances_page.py`
- [Reports](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/reports_page.py): `pocketlog/ui/reports_page.py`
- [Settlements](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/settlements_page.py): `pocketlog/ui/settlements_page.py`
- [Period filter](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/period_filter.py): `pocketlog/ui/period_filter.py`

### Expense domain

- [Participants](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/participants.py): `pocketlog/participants.py`
- [Expense records](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/expenses.py): `pocketlog/expenses.py`
- [Settlement records](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/settlements.py): `pocketlog/settlements.py`
- [Cards and repayments](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/cards.py): `pocketlog/cards.py`
- [Domain records](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/models.py): `pocketlog/models.py`
- [Exact-paise rules](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/money.py): `pocketlog/money.py`

### Balances and reporting

- [Report service](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/reports.py): `pocketlog/reports.py`
- [Balance calculation](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/balances.py): `pocketlog/balances.py`

### Local data

- [SQLite database](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/db.py): `pocketlog/db.py`
- [Data location](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/config.py): `pocketlog/config.py`

### Shared UI and money

- [Reusable widgets](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/widgets.py): `pocketlog/ui/widgets.py`
- [Light and dark themes](https://github.com/solitarybear/pocketlog/blob/main/pocketlog/ui/theme.py): `pocketlog/ui/theme.py`

### Other components

- **Group member**

## Connections

- Group member → Application startup: launches (evidence: `README.md`)
- Application startup → Navigation window: opens (evidence: `pocketlog/app.py`)
- Application startup → Data location: resolves data path (evidence: `pocketlog/app.py`)
- Application startup → SQLite database: opens (evidence: `pocketlog/app.py`)
- Navigation window → Expense editor and list: shows (evidence: `pocketlog/ui/main_window.py`)
- Navigation window → People and settings: shows (evidence: `pocketlog/ui/main_window.py`)
- Navigation window → Card activity: shows (evidence: `pocketlog/ui/main_window.py`)
- Navigation window → Dashboard: shows (evidence: `pocketlog/ui/main_window.py`)
- Navigation window → Balances: shows (evidence: `pocketlog/ui/main_window.py`)
- Navigation window → Reports: shows (evidence: `pocketlog/ui/main_window.py`)
- Navigation window → Settlements: shows (evidence: `pocketlog/ui/main_window.py`)
- Expense editor and list → Expense records: saves expenses (evidence: `pocketlog/ui/expense_dialog.py`)
- People and settings → Participants: manages people (evidence: `pocketlog/ui/settings_page.py`)
- Card activity → Cards and repayments: records repayments (evidence: `README.md`)
- Dashboard → Report service: requests summaries (evidence: `pocketlog/ui/dashboard_page.py`)
- Balances → Report service: requests balances (evidence: `pocketlog/ui/balances_page.py`)
- Reports → Report service: requests reports (evidence: `pocketlog/ui/reports_page.py`)
- Settlements → Report service: requests settlement data (evidence: `pocketlog/ui/settlements_page.py`)
- Period filter → Report service: resolves periods (evidence: `pocketlog/ui/period_filter.py`)
- Report service → Participants: reads participants (evidence: `pocketlog/reports.py`)
- Report service → Expense records: queries expenses (evidence: `pocketlog/reports.py`)
- Report service → Settlement records: queries settlements (evidence: `pocketlog/reports.py`)
- Report service → Cards and repayments: queries card activity (evidence: `pocketlog/reports.py`)
- Report service → Balance calculation: builds balances (evidence: `pocketlog/reports.py`)
- Participants → SQLite database: reads and writes (evidence: `pocketlog/participants.py`)
- Expense records → SQLite database: reads and writes (evidence: `pocketlog/expenses.py`)
- Settlement records → SQLite database: reads and writes (evidence: `pocketlog/settlements.py`)
- Cards and repayments → SQLite database: reads and writes (evidence: `pocketlog/cards.py`)
- Expense records → Exact-paise rules: validates splits (evidence: `pocketlog/expenses.py`)
- Expense editor and list → Exact-paise rules: computes split (evidence: `pocketlog/ui/expense_dialog.py`)
- Report service → Domain records: builds report records (evidence: `pocketlog/reports.py`)
- Expense records → Domain records: returns expense records (evidence: `pocketlog/expenses.py`)
- Navigation window → Reusable widgets: uses components (evidence: `pocketlog/ui/main_window.py`)
- Reusable widgets → Light and dark themes: uses styles (evidence: `pocketlog/ui/widgets.py`)
