# ilryaz/das-ist-ja-einfach architecture

> Architecture diagram of the GitHub repository ilryaz/das-ist-ja-einfach, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ilryaz/das-ist-ja-einfach
- Repository: https://github.com/ilryaz/das-ist-ja-einfach

## Overview

#### Purpose and Entry Point
A Python/PySide6 desktop productivity application for tracking study time, per-subject weekly goals, calendar history, and quick-add sessions. The executable entry point is `main.py`, which initializes the Qt application and main window.

#### Application Shell
The main desktop UI is centered on `app/main_window.py`. It owns the Qt Widgets window lifecycle, assembles plugin-provided content, and applies the selected visual theme. `app/__init__.py` establishes the application package boundary.

#### Plugin Loading Boundary
`app/plugin_manager.py` is the extension boundary between the shell and feature modules. It discovers/loads plugins from `plugins/`, allowing domain functionality to be organized independently of the core window. Plugin package roots are `plugins/__init__.py` and `plugins/school/__init__.py`.

#### School/Study Domain Plugin
The currently material feature is the school plugin:
- `plugins/school/plugin.py` defines the plugin integration contract/registration with the host.
- `plugins/school/page.py` supplies the Qt page and user interactions for subject management, time controls, weekly progress, and calendar-oriented tracking.
- `plugins/school/model.py` contains the domain state and persistence-facing logic, separating study data from widget code.

Primary flow: user interaction in the school page updates the school model; the model persists changed state to JSON; refreshed model state drives progress and calendar UI.

#### Persistence and Defaults
The application uses local JSON files under `data/`, with default templates used to bootstrap missing mutable files. Global preferences are represented by `data/settings.default.json` and `data/settings.json`. School-specific persisted state is partitioned into:
- `data/school/data.default.json` for baseline subject/session data,
- `data/school/week_config.json` with `week_config.default.json` for weekly-goal configuration,
- `data/school/time_buttons.json` with `time_buttons.default.json` for customizable quick-add durations.

This creates a clear boundary: checked-in default templates define initial schema/content, while non-default JSON files hold user state.

#### Themes and Presentation Assets
Themes are data-driven palettes in `themes/light.json`, `themes/dark.json`, and `themes/catppuccin.json`. `themes/template.qss` is the shared Qt stylesheet template, likely populated from a selected palette before applying it to the Qt application. Theme selection is therefore separate from feature/plugin UI logic.

#### Runtime and External Dependencies
Runtime is local desktop Python using PySide6 and Qt Widgets; no server, database, or external API is indicated. Persistence is filesystem-based via JSON and `pathlib`. The main operational boundary is therefore the local machine: Qt event loop/UI on one side, JSON-backed application and plugin state on the other.

Main entry points: [`app/main_window.py`](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/app/main_window.py) (Main window), [`plugins/school/model.py`](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/plugins/school/model.py) (Study model), [`plugins/school/plugin.py`](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/plugins/school/plugin.py) (School registration), [`app/plugin_manager.py`](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/app/plugin_manager.py) (Plugin manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Application Shell"]
  node_entry["Desktop entry point<br/>Python executable<br/>[main.py]"]
  node_main_window["Main window<br/>Qt Widgets shell<br/>[main_window.py]"]
  node_plugin_manager{{"Plugin manager<br/>extension loader<br/>[plugin_manager.py]"}}
  node_app_package["App package<br/>package boundary<br/>[__init__.py]"]
end

subgraph group_school["School Plugin"]
  node_school_plugin{{"School registration<br/>plugin contract<br/>[plugin.py]"}}
  node_school_page["Study page<br/>Qt feature page<br/>[page.py]"]
  node_school_model["Study model<br/>domain and persistence<br/>[model.py]"]
  node_plugins_root["Plugin packages<br/>package roots<br/>[__init__.py]"]
  node_school_package["School package<br/>package boundary<br/>[__init__.py]"]
end

subgraph group_storage["Local JSON Storage"]
  node_settings_defaults["Settings defaults<br/>JSON template"]
  node_settings_state["User settings<br/>JSON state<br/>[settings.json]"]
  node_school_defaults["School data defaults<br/>JSON template<br/>[data.default.json]"]
  node_week_config["Weekly goals<br/>JSON state and template<br/>[week_config.json]"]
  node_time_buttons["Quick-add durations<br/>JSON state and template<br/>[time_buttons.json]"]
end

subgraph group_theme["Theme Assets"]
  node_theme_palettes["Theme palettes<br/>JSON palettes<br/>[light.json]"]
  node_stylesheet_template["Qt stylesheet template<br/>QSS template<br/>[template.qss]"]
end

node_entry -->|"starts"| node_main_window
node_main_window -->|"loads content through"| node_plugin_manager
node_plugin_manager -->|"discovers and loads"| node_school_plugin
node_school_plugin -->|"provides"| node_school_page
node_school_page -->|"updates and refreshes from"| node_school_model
node_school_model -.->|"bootstraps from"| node_school_defaults
node_school_model -->|"persists weekly goals"| node_week_config
node_school_model -->|"persists quick-add settings"| node_time_buttons
node_main_window -->|"uses preferences"| node_settings_state
node_settings_defaults -.->|"bootstraps missing state"| node_settings_state
node_main_window -->|"selects palette"| node_theme_palettes
node_theme_palettes -->|"populates"| node_stylesheet_template
node_stylesheet_template -->|"applies Qt styling"| node_main_window
node_plugins_root -->|"contains"| node_school_package
node_school_package -->|"contains"| node_school_plugin

click node_entry "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/main.py"
click node_main_window "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/app/main_window.py"
click node_plugin_manager "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/app/plugin_manager.py"
click node_app_package "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/app/__init__.py"
click node_school_plugin "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/plugins/school/plugin.py"
click node_school_page "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/plugins/school/page.py"
click node_school_model "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/plugins/school/model.py"
click node_plugins_root "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/plugins/__init__.py"
click node_school_package "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/plugins/school/__init__.py"
click node_settings_defaults "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/data/settings.default.json"
click node_settings_state "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/data/settings.json"
click node_school_defaults "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/data/school/data.default.json"
click node_week_config "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/data/school/week_config.json"
click node_time_buttons "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/data/school/time_buttons.json"
click node_theme_palettes "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/themes/light.json"
click node_stylesheet_template "https://github.com/ilryaz/das-ist-ja-einfach/blob/main/themes/template.qss"

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_entry,node_main_window,node_plugin_manager,node_app_package toneBlue
class node_school_plugin,node_school_page,node_school_model,node_plugins_root,node_school_package toneAmber
class node_settings_defaults,node_settings_state,node_school_defaults,node_week_config,node_time_buttons toneMint
class node_theme_palettes,node_stylesheet_template toneRose
```

## Components

### Application Shell

- [Desktop entry point](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/main.py): Python executable · Initializes Qt and the main window. · `main.py`
- [Main window](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/app/main_window.py): Qt Widgets shell · Owns window lifecycle, plugin content, and theme application. · `app/main_window.py`
- [Plugin manager](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/app/plugin_manager.py): extension loader · Discovers and loads feature plugins. · `app/plugin_manager.py`
- [App package](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/app/__init__.py): package boundary · `app/__init__.py`

### School Plugin

- [School registration](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/plugins/school/plugin.py): plugin contract · Registers the school feature with the host. · `plugins/school/plugin.py`
- [Study page](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/plugins/school/page.py): Qt feature page · Handles subjects, timers, weekly progress, and calendar interactions. · `plugins/school/page.py`
- [Study model](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/plugins/school/model.py): domain and persistence · Owns study state and JSON-backed updates. · `plugins/school/model.py`
- [Plugin packages](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/plugins/__init__.py): package roots · `plugins/__init__.py`
- [School package](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/plugins/school/__init__.py): package boundary · `plugins/school/__init__.py`

### Local JSON Storage

- [Settings defaults](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/data/settings.default.json): JSON template · Bootstrap preferences schema and values. · `data/settings.default.json`
- [User settings](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/data/settings.json): JSON state · Persisted global preferences. · `data/settings.json`
- [School data defaults](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/data/school/data.default.json): JSON template · Baseline subject and session data. · `data/school/data.default.json`
- [Weekly goals](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/data/school/week_config.json): JSON state and template · Weekly-goal configuration and its defaults. · `data/school/week_config.json`
- [Quick-add durations](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/data/school/time_buttons.json): JSON state and template · Customizable time-button configuration and defaults. · `data/school/time_buttons.json`

### Theme Assets

- [Theme palettes](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/themes/light.json): JSON palettes · Light, dark, and Catppuccin palette data. · `themes/light.json`
- [Qt stylesheet template](https://github.com/ilryaz/das-ist-ja-einfach/blob/main/themes/template.qss): QSS template · Shared stylesheet populated from the selected palette. · `themes/template.qss`

## Connections

- Desktop entry point → Main window: starts
- Main window → Plugin manager: loads content through
- Plugin manager → School registration: discovers and loads
- School registration → Study page: provides
- Study page → Study model: updates and refreshes from
- Study model → School data defaults: bootstraps from
- Study model → Weekly goals: persists weekly goals
- Study model → Quick-add durations: persists quick-add settings
- Main window → User settings: uses preferences
- Settings defaults → User settings: bootstraps missing state
- Main window → Theme palettes: selects palette
- Theme palettes → Qt stylesheet template: populates
- Qt stylesheet template → Main window: applies Qt styling
- Plugin packages → School package: contains
- School package → School registration: contains