# clockworksspheres/eisenban architecture

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

- Interactive diagram: https://gitdiagram.com/clockworksspheres/eisenban
- Repository: https://github.com/clockworksspheres/eisenban

## Overview

##### Project type and purpose
- This is a desktop “Kanban-style” task‐management application written in Python and Qt (PyQt).
- It contains two parallel code bases: “kanbaru” (upstream, frozen) and “eisenban” (rebranded, under active development).
- Core features: create/manage boards, lists, cards; persistent storage; customizable UI; cross-platform packaging.

##### File structure
- Top‐level directories:
- src/eisenban – the main application code for the rebranded fork
- src/kanbaru – original codebase, same internal structure
- src/tests – unit tests for core libraries
- Common submodules under each code base:
- ui – Qt .ui definitions, generated Python UI wrappers, controllers
- dialog.py, main.py – entry points for application runtime
- db.py – data‐access layer (likely SQLite)
- eisenban_objects.py / kanbaru_objects.py – domain models (Board, List, Card)
- lib/ – shared helper modules (logging, command runners, environment detection, singleton pattern)
- proto/ – exploratory/prototyping scripts, proof‐of‐concept for signals, resources
- packaging scripts – platform‐specific build scripts and spec files (macOS, Linux, Windows)

##### README insights
- Purpose: preserve Kanbaru’s functionality, add enhancements in Eisenban.
- Dependencies declared in requirements.txt (PyQt5, SQLite, others).

##### Main components
a. UI Layer
- Qt Widgets / .ui files
- Controllers in ui/*.py (MainWindow, Dialogs, Settings)
b. Domain Layer
- Domain models in *objects.py (Board, List, Card)
- Business logic in dialog.py, utils.py
c. Data Access Layer
- db.py – CRUD operations on SQLite
- config.py – app settings (file paths, user preferences)
d. Infrastructure & Helpers
- lib/ modules – logging, environment detection, command execution
- proto/ – experimental/prototype code (can be shown as “Research/Prototype” cluster)
e. Packaging/Deployment
- Platform build scripts (eisenbuild.*) & spec files
- Packaging tool (PyInstaller)
- Resources compilation (gen_qrc-*.py, QRC → Python resources)
f. Tests
- src/tests – unit tests exercising lib/ and db modules

##### Component relationships and interactions
- UI Layer → invokes Domain Layer methods
- Domain Layer → reads/writes via Data Access Layer
- Data Access Layer → persists to SQLite database file
- UI Layer → loads resources via compiled resource module (resources_rc.py)
- Packaging scripts → bundle all code, resources, Qt runtime into standalone executables
- lib/ utilities → injected into Domain & Data Access layers for logging & environment checks
- Tests → import lib/ and db.py to verify core functionality

##### Architectural patterns and principles
- MVC‐like separation:
- Views (Qt .ui + generated wrappers)
- Controllers (ui/*.py providing event handlers)
- Models (domain objects + data‐access)
- Singletons for application‐wide configuration/logging

##### Technologies, frameworks, and libraries
- Python 3.x
- PyQt5 (Qt Designer .ui files → pyuic-generated code)
- SQLite (via Python’s sqlite3)
- PyInstaller (onefile and spec scripts)

2. UI components on the left:
– Widgets (.ui files) → Generated UI classes → Controller classes.
3. In the middle, place Domain Models and Utility modules.
5. At the bottom or side, cluster Packaging & Deployment: build scripts, spec files, output executables.
6. At the top or side, cluster Tests and Prototypes (proto/) as separate offshoot modules.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        UIFiles["Qt .ui Files"]:::resources
        UICompile["compile_uifiles.py"]:::resources
        GenUI["Generated UI Classes"]:::core
        Controllers["Controller Classes"]:::core
    end

    %% Core Logic Layer
    subgraph "Core Logic"
        Entry["Application Entry Point"]:::core
        Domain["Domain Models (Board, List, Card)"]:::core
        Dialogs["Dialog Controllers"]:::core
        Utils["Utility Functions"]:::helpers
        Config["Application Configuration"]:::core
        Infra["Infrastructure Helpers (lib/)"]:::helpers
    end

    %% Persistence Layer
    subgraph "Persistence"
        DAL["Data Access Layer (db.py)"]:::core
        DB["SQLite Database"]:::db
    end

    %% Resources
    subgraph "Resources"
        QRC["Qt Resource Definition (.qrc)"]:::resources
        RC["Compiled Resources Module"]:::resources
        Assets["Resource Assets (icons, fonts)"]:::resources
    end

    %% Prototype / Experimental
    subgraph "Research / Prototype"
        Proto["Experimental / Prototype Code"]:::helpers
    end

    %% Tests
    subgraph "Unit Tests"
        Tests["src/tests"]:::packaging
    end

    %% Packaging & Deployment
    subgraph "Packaging & Deployment"
        PkgSpecLinux["eisenbuild.linux.spec"]:::packaging
        PkgSpecMac["eisenbuild.macos.spec"]:::packaging
        PkgSpecWin["eisenbuild.windows11.onefile.spec"]:::packaging
        PkgScriptMac["eisenbuild.macos.sh"]:::packaging
        PyInstaller["PyInstaller Tool"]:::packaging
        Exec["Standalone Executables"]:::packaging
    end

    %% Connections
    UIFiles -->|"generate UI code"| GenUI
    UICompile --> GenUI
    GenUI -->|"used by"| Controllers
    Controllers -->|"invoke methods"| Domain
    Controllers -->|"load resources"| RC

    Entry --> Domain
    Dialogs --> Domain

    Domain -->|"uses"| Utils
    Domain -->|"reads config"| Config
    Domain -->|"uses helpers"| Infra
    Domain -->|"read/write"| DAL
    DAL -->|"persist"| DB

    QRC -->|"compile to"| RC
    Assets --> RC

    Proto -.-> Controllers
    Proto -.-> Domain

    Tests -->|"verify utilities"| Utils
    Tests -->|"verify data access"| DAL

    PyInstaller -->|"bundles all components"| Exec
    PkgSpecLinux --> Exec
    PkgSpecMac --> Exec
    PkgSpecWin --> Exec
    PkgScriptMac --> Exec

    %% Click Events
    click UIFiles "https://github.com/clockworksspheres/eisenban/tree/main/src/eisenban/ui"
    click UICompile "https://github.com/clockworksspheres/eisenban/blob/main/src/eisenban/ui/compile_uifiles.py"
    click Controllers "https://github.com/clockworksspheres/eisenban/tree/main/src/eisenban/ui"
    click Domain "https://github.com/clockworksspheres/eisenban/blob/main/src/eisenban/eisenban_objects.py"
    click Dialogs "https://github.com/clockworksspheres/eisenban/blob/main/src/eisenban/dialog.py"
    click Entry "https://github.com/clockworksspheres/eisenban/blob/main/src/eisenban/eisenban.py"
    click Utils "https://github.com/clockworksspheres/eisenban/blob/main/src/eisenban/utils.py"
    click Config "https://github.com/clockworksspheres/eisenban/blob/main/src/eisenban/config.py"
    click Infra "https://github.com/clockworksspheres/eisenban/tree/main/src/eisenban/lib"
    click DAL "https://github.com/clockworksspheres/eisenban/blob/main/src/eisenban/db.py"
    click QRC "https://github.com/clockworksspheres/eisenban/blob/main/src/eisenban/eisenban.qrc"
    click RC "https://github.com/clockworksspheres/eisenban/blob/main/src/eisenban/eisenban_rc.py"
    click Assets "https://github.com/clockworksspheres/eisenban/tree/main/src/eisenban/resources"
    click Proto "https://github.com/clockworksspheres/eisenban/tree/main/src/eisenban/proto"
    click Tests "https://github.com/clockworksspheres/eisenban/tree/main/src/tests"
    click PkgSpecLinux "https://github.com/clockworksspheres/eisenban/blob/main/src/eisenban/eisenbuild.linux.spec"
    click PkgSpecMac "https://github.com/clockworksspheres/eisenban/blob/main/src/eisenban/eisenbuild.macos.spec"
    click PkgSpecWin "https://github.com/clockworksspheres/eisenban/blob/main/src/eisenban/eisenbuild.windows11.onefile.spec"
    click PkgScriptMac "https://github.com/clockworksspheres/eisenban/blob/main/src/eisenban/eisenbuild.macos.sh"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef helpers fill:#d4edda,stroke:#333,stroke-width:1px
    classDef db fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef resources fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef packaging fill:#e2e3e5,stroke:#333,stroke-width:1px
```
