ADR 0001: GUI Monolith Refactoring Plan

Status: Accepted
Date: 2026-04-20
Deciders: Engineering lead, Principal architect

Context

Omnis Helix's GUI layer contains several monolithic Python files that concentrate view logic, event handling, rendering adapters, and business rules in single modules:

These files exceed effective code-review thresholds and create critical-person risk for a 7-person team. If the principal GUI author leaves, maintenance velocity collapses.

Decision

We will incrementally refactor the GUI layer using a component-boundary strategy rather than a risky big-bang rewrite. The goal is to reduce the largest files to <2,000 lines within 12 months.

Consequences

Positive

• Reduced critical-person risk
• Faster code reviews (<30 min per PR)
• Easier onboarding for new frontend hires
• Better separation between view logic and domain logic

Negative

• Refactoring a Qt thick-client is labor-intensive; some widgets resist clean decomposition
• Risk of regressions in undo/redo and OpenGL rendering paths
• Requires dedicated frontend bandwidth for 2–3 sprints

Strategy

Phase 1: Extract pure functions (Month 1–2)

Move stateless logic out of GUI files:

• Filter/sort logic → src/helix/gui/presenters/
• Export formatting → src/helix/gui/formatters/
• Color/theme constants → src/helix/gui/tokens.py

Phase 2: Widget decomposition (Month 3–6)

Split large widgets into smaller, testable components:

• outcome_explorer.py → outcome_explorer/ package
  • chart_pane.py, filter_bar.py, export_dialog.py, detail_sidebar.py
• main_window.py → main_window/ package
  • menu_bar.py, dock_manager.py, status_bar.py, shortcut_manager.py

Phase 3: View-model separation (Month 7–9)

Introduce lightweight view-models (not full MVVM) to isolate Qt-specific code from business rules:

• src/helix/gui/viewmodels/
• Goal: Qt imports only in viewmodels/ and top-level widget files

Phase 4: Test harness (Month 10–12)

• Add pytest-qt tests for critical user flows
• Target: 60% GUI line coverage (currently ~5%)

Risks and Mitigations

Compliance Note

This ADR does not affect SOC2/HIPAA/GDPR controls. GUI refactoring is an internal engineering-quality initiative.

References

• src/helix/gui/outcome_explorer.py
• src/helix/gui/main_window.py
• src/helix/studio/simbuilder/app.py
• docs/dev/SECURITY_HARDENING.md