| # GUI-Architektur — 3 Standalone GTK3 Apps |
|
|
| Stand: 2026-03-04 |
|
|
| ## 1. Shared Base Module (`~/Projekte/shared-gui/gui_base.py`) |
| |
| Gemeinsame Grundlage fuer alle drei GUIs. Importiert `theme.py` aus ClaudeCodePanel. |
| |
| ### BaseApp Klasse |
| |
| ```python |
| class BaseApp(Gtk.Window): |
| def __init__(self, title, width, height, icon_name=None) |
| ``` |
| |
| Bereitgestellte Features: |
| - **Window Setup**: Titel, Groesse, Icon, `destroy`-Signal |
| - **HeaderBar**: Gtk.HeaderBar mit Titel + optionalem Subtitle |
| - **StatusBar**: Unten, CSS-Klasse `.status-bar`, mit `set_status(text, css_class)` Methode |
| - **Theme**: Automatisches Laden von Catppuccin CSS via `theme.py`, COSMIC dark/light Watcher |
| - **CSS Provider**: Gemeinsam fuer alle Widgets, erweiterbar via `add_css(css_string)` |
| - **Refresh Timer**: `start_refresh(interval_seconds, callback)` — GLib.timeout_add_seconds |
| - **Main Box**: Vertikaler Gtk.Box (`self.content_box`) zwischen Header und StatusBar |
| |
| ### Theme-Modul Wiederverwendung |
| |
| `gui_base.py` importiert direkt aus ClaudeCodePanel: |
| ```python |
| sys.path.insert(0, str(Path.home() / "Projekte/ClaudeCodePanel")) |
| from theme import build_css, setup_theme_watcher, get_palette, is_dark_mode |
| ``` |
| |
| ### Gemeinsame CSS-Klassen (aus theme.py) |
| |
| Alle Apps erben automatisch: |
| - `.panel-header`, `.stat-value`, `.stat-label` — Ueberschriften + Statistiken |
| - `.section-frame`, `.section-title` — Karten/Sektionen |
| - `.status-bar`, `.status-saved`, `.status-error` — Statusleiste |
| - `.shortcut-btn` — Aktionsbuttons |
| - `.monitor-value`, `.cost-value` — Monospace-Werte |
| |
| Zusaetzlich definiert gui_base.py: |
| - `.base-card` — Standardkarte (border-radius 8px, card-bg, border) |
| - `.base-toolbar` — Toolbar-Leiste (mantle-bg, border-radius 8px) |
| - `.base-badge` — Kleine Status-Badges (border-radius 12px) |
| |
| --- |
| |
| ## 2. Design-Specs pro GUI |
| |
| ### 2.1 Sidecar-GUI (`~/Projekte/Sidecar/gui/`) |
| |
| **Zweck:** Visuelles Dashboard fuer den Sidecar Daemon — Rules, Sessions, Findings. |
| |
| **Layout:** |
| ``` |
| +-----------------------------------------------+ |
| | [HeaderBar] Sidecar Control Panel [Reload] | |
| +-----------------------------------------------+ |
| | [Notebook] | |
| | +-------------------------------------------+ | |
| | | Tab: Status | Tab: Rules | Tab: Findings | | |
| | +-------------------------------------------+ | |
| | | |
| | STATUS TAB: | |
| | Daemon: running PID: 12345 Uptime: 2h 15m | |
| | Rules: 22 Findings: 5 Plugins: 3 | |
| | | |
| | RULES TAB: | |
| | [SearchEntry filter] | |
| | +------------------------------------------+ | |
| | | Name | Group | Enabled | Fires | | |
| | | cli_first | enforce | [x] | 12 | | |
| | | gate_rm_rf | gate | [x] | 3 | | |
| | +------------------------------------------+ | |
| | [Enable] [Disable] [Snooze 30m] | |
| | | |
| | FINDINGS TAB: | |
| | [ScrolledWindow mit Finding-Cards] | |
| | Time | Rule | Severity | Message | |
| +-----------------------------------------------+ |
| | [StatusBar] Connected via /tmp/claude-sidecar.sock | |
| +-----------------------------------------------+ |
| ``` |
| |
| **Widgets:** |
| - `Gtk.Notebook` mit 3 Tabs |
| - Status-Tab: Grid mit Labels (key-value), aktualisiert via Refresh |
| - Rules-Tab: `Gtk.ListBox` mit Rows, SearchEntry fuer Filter, Toggle-Buttons |
| - Findings-Tab: `Gtk.ListBox` mit farbcodierten Karten (Severity → Farbe) |
| |
| **Datenquellen:** |
| - Primaer: Unix Socket `/tmp/claude-sidecar.sock` (JSON-Protokoll, wie sidecar-ctl) |
| - Kommandos: `status`, `rules`, `findings`, `enable`, `disable`, `snooze`, `reload` |
| - Socket-Kommunikation non-blocking via `GLib.io_add_watch` auf Socket-FD |
| |
| **Refresh:** 5 Sekunden (Status + Rules), Findings on-demand |
| |
| **Interaktion:** |
| - Rules: Klick auf Row → Enable/Disable Toggle, Rechtsklick → Snooze |
| - Findings: Nur Anzeige, scrollbar |
| - Reload-Button in HeaderBar |
| |
| --- |
| |
| ### 2.2 Tools-GUI (`~/Projekte/ClaudeCodePanel/tools-gui/`) |
| |
| **Zweck:** Session-History + Kosten-Tracking fuer Claude Code. |
| |
| **Layout:** |
| ``` |
| +-----------------------------------------------+ |
| | [HeaderBar] Claude Code Tools [Ref] | |
| +-----------------------------------------------+ |
| | [Notebook] | |
| | +-------------------------------------------+ | |
| | | Tab: Sessions | Tab: Costs | Tab: Tools | | |
| | +-------------------------------------------+ | |
| | | |
| | SESSIONS TAB: | |
| | [SearchEntry] [ComboBox: Sortierung] | |
| | +------------------------------------------+ | |
| | | Projekt | Letztes Msg | Kosten | Res | | |
| | | Sidecar | vor 2h | $0.12 | [>] | | |
| | | ClaudePanel | vor 1d | $0.45 | [>] | | |
| | +------------------------------------------+ | |
| | | |
| | COSTS TAB: | |
| | Heute: $1.23 Woche: $8.50 Monat: $32.10 | |
| | [BarChart via DrawingArea — letzte 7 Tage] | |
| | Top Tools: Read(45) Edit(23) Bash(18) | |
| | | |
| | TOOLS TAB: | |
| | Tool-Usage Breakdown (ListBox) | |
| | Skill-Usage + Missed Skills | |
| +-----------------------------------------------+ |
| | [StatusBar] 12 Sessions | $1.23 heute | |
| +-----------------------------------------------+ |
| ``` |
| |
| **Widgets:** |
| - Sessions-Tab: `Gtk.ListBox` mit Session-Rows, SearchEntry, ComboBox fuer Sortierung |
| - Costs-Tab: Stat-Labels oben, `Gtk.DrawingArea` fuer 7-Tage-Balkendiagramm (Cairo), Tool-Rankings |
| - Tools-Tab: `Gtk.ListBox` mit Tool-Usage, Skill-Usage |
| |
| **Datenquellen:** |
| - `monitor.py` Funktionen: `get_daily_cost()`, `get_top_tools()`, `get_recent_sessions()`, `get_usage_timeline()`, `get_provider_costs()`, `get_skill_usage()`, `get_missed_skills_summary()` |
| - Import: `sys.path.insert(0, "~/Projekte/ClaudeCodePanel")` + `from monitor import ...` |
|
|
| **Refresh:** 30 Sekunden (passend zum TTL-Cache in monitor.py) |
|
|
| --- |
|
|
| ### 2.3 Florian-GUI (`~/Projekte/MyAIGame/florian-gui/`) |
|
|
| **Zweck:** TTS Control Panel — Voice-Auswahl, Test, Speed/Pitch, Audio-Playback. |
|
|
| **Layout:** |
| ``` |
| +-----------------------------------------------+ |
| | [HeaderBar] Florian TTS Control [Play] | |
| +-----------------------------------------------+ |
| | | |
| | Voice: [ComboBox: florian|katja|conrad|...] | |
| | | |
| | Speed: [=====|========] 1.0x | |
| | Pitch: [=====|========] +0Hz | |
| | | |
| | Format: ( ) mp3 ( ) wav ( ) opus ( ) flac | |
| | | |
| | Text: | |
| | +------------------------------------------+ | |
| | | Guten Tag, ich bin Florian und teste | | |
| | | die Sprachausgabe. | | |
| | +------------------------------------------+ | |
| | | |
| | [ Speak ] [Stop] | |
| | | |
| | +------------------------------------------+ | |
| | | Audio-Wellenform / Fortschrittsbalken | | |
| | +------------------------------------------+ | |
| | | |
| | Server: localhost:5050 [Health: OK] | |
| +-----------------------------------------------+ |
| | [StatusBar] Ready — Florian (de-DE) | |
| +-----------------------------------------------+ |
| ``` |
|
|
| **Widgets:** |
| - `Gtk.ComboBoxText` fuer Voice-Auswahl (aus `/v1/audio/voices` Endpoint) |
| - `Gtk.Scale` fuer Speed (0.25 — 4.0, Step 0.25) und Pitch (-20Hz — +20Hz) |
| - `Gtk.RadioButton` Gruppe fuer Format |
| - `Gtk.TextView` fuer Text-Eingabe (mehrzeilig) |
| - `Gtk.Button` Speak + Stop |
| - `Gtk.ProgressBar` fuer Audio-Playback |
| - Health-Indikator (Label mit Farbcode) |
|
|
| **Datenquellen:** |
| - HTTP API: `http://localhost:5050` |
| - `GET /v1/audio/voices` → Voice-Liste |
| - `POST /v1/audio/speech` → Audio-Bytes (body: `{input, voice, speed, response_format}`) |
| - `GET /health` → Server-Status |
| - HTTP via `Gio.InputStream` / subprocess `curl` + GLib.spawn_async (kein threading!) |
| |
| **Audio-Playback:** |
| - Tempfile schreiben → `subprocess.Popen(["mpv", "--no-video", tmpfile])` via `GLib.spawn_async` |
| - Stop = Kill des mpv-Prozesses |
|
|
| **Refresh:** Health-Check alle 10 Sekunden |
|
|
| --- |
|
|
| ## 3. Dateistruktur pro Projekt |
|
|
| ### shared-gui/ |
| ``` |
| ~/Projekte/shared-gui/ |
| gui_base.py # BaseApp + Theme-Integration + gemeinsame CSS |
| ``` |
|
|
| ### Sidecar-GUI |
| ``` |
| ~/Projekte/Sidecar/gui/ |
| main.py # Entry-Point, SidecarApp(BaseApp) |
| socket_client.py # Non-blocking Unix Socket Client (GLib.io_add_watch) |
| tabs/ |
| status_tab.py # Daemon-Status Anzeige |
| rules_tab.py # Rules ListBox + Filter + Enable/Disable |
| findings_tab.py # Findings ListBox |
| ``` |
|
|
| ### Tools-GUI |
| ``` |
| ~/Projekte/ClaudeCodePanel/tools-gui/ |
| main.py # Entry-Point, ToolsApp(BaseApp) |
| tabs/ |
| sessions_tab.py # Session-ListBox + Search + Sort |
| costs_tab.py # Kosten-Stats + Cairo BarChart |
| tools_tab.py # Tool-Usage + Skill-Usage |
| ``` |
|
|
| ### Florian-GUI |
| ``` |
| ~/Projekte/MyAIGame/florian-gui/ |
| main.py # Entry-Point, FlorianApp(BaseApp) |
| tts_client.py # HTTP Client (Gio/subprocess, non-blocking) |
| audio_player.py # mpv-basierter Player (GLib.spawn_async) |
| ``` |
|
|
| --- |
|
|
| ## 4. Constraints |
|
|
| | Constraint | Detail | |
| |-----------|--------| |
| | **Toolkit** | GTK 3.0 via PyGObject (`gi.require_version("Gtk", "3.0")`) | |
| | **Theme** | Catppuccin Mocha (dark) / Latte (light) via `theme.py` | |
| | **Desktop** | COSMIC — `is_dark_mode()` liest `~/.config/cosmic/CosmicTheme.Mode/v1/is_dark` | |
| | **Event Loop** | GLib Main Loop — KEIN threading, KEIN asyncio im GUI-Thread | |
| | **Timer** | `GLib.timeout_add_seconds()` fuer Refresh, Return `True` fuer Repeat | |
| | **Non-Blocking I/O** | Socket: `GLib.io_add_watch`, HTTP: `GLib.spawn_async` mit Callback | |
| | **CSS** | Alle Styles via `Gtk.CssProvider`, keine inline-Styles | |
| | **GLib.idle_add** | Nur als One-Shot (`return False`), NIE mit `return True` | |
| | **Python** | 3.11+ (match/case erlaubt, aber nicht erforderlich) | |
| | **Abhaengigkeiten** | PyGObject >= 3.42, gir1.2-gtk-3.0 (keine zusaetzlichen Pakete) | |
| |
