# projecthamster/hamster architecture

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

- Interactive diagram: https://gitdiagram.com/projecthamster/hamster
- Repository: https://github.com/projecthamster/hamster

## Overview

##### Project type and purpose
- This is a standalone, single-module desktop time-tracking application (“Hamster”) written in Python 3 and GTK3.
- It provides a background daemon (the service), a command-line client, and a GUI client, all coordinated via D-Bus, persisting data in a local SQLite database.

##### File-structure analysis
- Top-level folders:
- help/ & po/ – Mallard help pages and translation files
- src/ – all Python code
· hamster-cli.py, hamster-service.py, hamster-windows-service.py – entry points
· src/hamster/ – core module
– lib/ – core libraries (configuration, charting, i18n, D-Bus helpers, parsing, etc.)
– storage/ – database layer (SQLite access)
– widgets/ – GUI widgets (activity entry, overview, reports, etc.)
- waf & wscript – build and installation scripts
- tests/ – unit tests
- Key configuration: D-Bus interfaces, UI definitions (.ui), gschema, Flatpak YAML.

##### README insights
- Confirms the D-Bus client-server architecture (daemon + clients).
- Lists dependencies (Python-GI/GTK, D-Bus, intltool, etc.).
- Describes development workflow: launching service & CLI for live testing, backing up the DB, packaging via Waf/Flatpak.

##### Diagramming the architecture
- User interfaces
– CLI client (hamster-cli.py)
– GUI client (GTK widgets via python src/hamster/)
- Client library (src/hamster/client.py + lib/*)
- IPC layer (D-Bus)
- Service daemon (hamster-service.py)
- Storage layer (src/hamster/storage + SQLite database file)
- Build/packaging subsystem (Waf, Flatpak)
- External dependencies (GTK3, Python3 runtime, intltool, OS D-Bus)
1. UI → Client library → D-Bus API → Service daemon
2. Service daemon → Storage layer (read/write SQLite)
3. Service daemon → D-Bus → UI (events/updates)
4. Build system → bundles code + assets → OS packages / Flatpak
c. Architectural patterns and principles:
- Client-server via D-Bus for decoupling UI and data logic
- Layered separation: presentation (UI), application (client lib & daemon), persistence (storage)
- Extensibility via modular lib/ and widgets/ subpackages
d. Key technologies and libraries:
- Python 3.6+, PyGObject (GTK3, Cairo), Python-DBus
- SQLite for local persistence
- Waf build system, Flatpak packaging, intltool / gettext for i18n

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interfaces
    subgraph "User Interfaces"
        CLI["CLI Client\nhamster-cli.py"]:::frontend
        GUI["GUI Client\nGTK3 GUI"]:::frontend
        UI["UI Definitions (.ui files)"]:::frontend
        Widgets["GUI Widgets (widgets/)"]:::frontend
    end

    %% Client Library & IPC
    subgraph "Client Library & IPC"
        ClientAPI["Client API\nsrc/hamster/client.py"]:::logic
        IPC["D-Bus IPC\nlib/dbus.py"]:::logic
    end

    %% Service Daemon
    subgraph "Service Daemon"
        Daemon["Service Daemon\nhamster-service.py"]:::logic
        WinShim["Windows Shim\nhamster-windows-service.py"]:::logic
    end

    %% Storage Layer
    subgraph "Storage Layer"
        DBAccess["DB Access\nsrc/hamster/storage/db.py"]:::storage
        StorageAbst["Storage Abstraction\nsrc/hamster/storage/storage.py"]:::storage
        DB["SQLite Database File\ndata/hamster.db"]:::storage
    end

    %% Configuration & Metadata
    subgraph "Configuration & Metadata"
        GSchema["GSettings & D-Bus Schema\norg.gnome.hamster.gschema.xml"]:::metadata
        DesktopFiles["Desktop Service Files\n*.service.in/.desktop.in"]:::metadata
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        Waf["Waf Build System\nwscript & waf"]:::build
        Flatpak["Flatpak Manifest\ndata/org.gnome.Hamster.flatpak.yml"]:::build
    end

    %% Dependencies (external)
    subgraph "External Dependencies"
        Python["Python3, PyGObject\nGTK3, D-Bus"]:::external
        SQLite["SQLite"]:::external
    end

    %% Connections
    CLI -->|uses| ClientAPI
    GUI -->|uses| ClientAPI
    UI -->|loaded by| GUI
    Widgets -->|used by| GUI

    ClientAPI -->|calls| IPC
    IPC -->|sends requests| Daemon
    Daemon -->|reads/writes| DBAccess
    DBAccess -->|persists to| DB
    Daemon -->|emits signals| IPC
    IPC -->|updates| GUI

    Daemon -->|relies on| GSchema
    GUI -->|relies on| GSchema
    Daemon -->|installed via| DesktopFiles
    GUI -->|installed via| DesktopFiles

    Waf -->|builds| CLI
    Waf -->|builds| GUI
    Waf -->|packages| Daemon
    Waf -->|includes assets| UI & DesktopFiles & GSchema
    Flatpak -->|packages| Waf
    Flatpak -->|bundles| Python & SQLite

    Python -->|runtime| CLI
    Python -->|runtime| GUI
    SQLite -->|storage engine| DB

    %% Click Events
    click CLI "https://github.com/projecthamster/hamster/blob/master/src/hamster-cli.py"
    click GUI "https://github.com/projecthamster/hamster/blob/master/src/hamster/edit_activity.py"
    click UI "https://github.com/projecthamster/hamster/blob/master/data/date_range.ui"
    click Widgets "https://github.com/projecthamster/hamster/blob/master/src/hamster/widgets/activityentry.py"
    click ClientAPI "https://github.com/projecthamster/hamster/blob/master/src/hamster/client.py"
    click IPC "https://github.com/projecthamster/hamster/blob/master/src/hamster/lib/dbus.py"
    click Daemon "https://github.com/projecthamster/hamster/blob/master/src/hamster-service.py"
    click WinShim "https://github.com/projecthamster/hamster/blob/master/src/hamster-windows-service.py"
    click DBAccess "https://github.com/projecthamster/hamster/blob/master/src/hamster/storage/db.py"
    click StorageAbst "https://github.com/projecthamster/hamster/blob/master/src/hamster/storage/storage.py"
    click DB "https://github.com/projecthamster/hamster/blob/master/data/hamster.db"
    click GSchema "https://github.com/projecthamster/hamster/blob/master/data/org.gnome.hamster.gschema.xml"
    click DesktopFiles "https://github.com/projecthamster/hamster/blob/master/data/org.gnome.Hamster.service.in"
    click Waf "https://github.com/projecthamster/hamster/tree/master/wscript"
    click Flatpak "https://github.com/projecthamster/hamster/blob/master/data/org.gnome.Hamster.flatpak.yml"

    %% Styles
    classDef frontend fill:#D0E7FF,stroke:#0366D6,color:#0366D6;
    classDef logic fill:#E6FFEB,stroke:#28A745,color:#28A745;
    classDef storage fill:#FFF4E6,stroke:#FF8C00,color:#FF8C00;
    classDef build fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef metadata fill:#F5E6FF,stroke:#6F42C1,color:#6F42C1;
    classDef external fill:#EAEAEA,stroke:#444444,color:#444444;
```
