Architecture Patterns

1. Key Classes

Core Singletons

MainWindow Coordinators (OpenSpec #00038)

Plugin Security

2. Design Patterns Used

Singleton

• •SettingsManager, ArtProvider, ThemeManager, IconRegistry, Logger
• •Access: ClassName::getInstance()

Command Pattern

• •CommandRegistry stores CommandDef entries
• •Actions created via ArtProvider::createAction()

Observer (Qt Signals/Slots)

• •ThemeManager::themeChanged signal
• •ArtProvider::resourcesChanged signal
• •Components connect to update on changes

Composite

• •Book → Part → Chapter (Document)
• •BookElement hierarchy

3. Source Structure

include/kalahari/
├── core/           # business logic, singletons
│   ├── art_provider.h
│   ├── settings_manager.h
│   ├── theme_manager.h
│   ├── icon_registry.h
│   ├── logger.h
│   ├── book.h
│   ├── document.h
│   ├── plugin_signature.h    # Ed25519 verification
│   └── trusted_keys.h        # Publisher key management
├── gui/            # UI components
│   ├── main_window.h         # Thin orchestrator
│   ├── icon_registrar.h      # Icon registration
│   ├── command_registrar.h   # Command registration
│   ├── dock_coordinator.h    # Panel management
│   ├── document_coordinator.h
│   ├── navigator_coordinator.h
│   ├── diagnostic_controller.h
│   ├── settings_coordinator.h
│   ├── command_registry.h
│   ├── settings_dialog.h
│   ├── panels/
│   │   ├── editor_panel.h
│   │   ├── navigator_panel.h
│   │   └── log_panel.h
│   └── utils/
│       └── layout_utils.h    # clearLayout() helper
└── utils/          # utilities
    └── ...

src/
├── core/
├── gui/
└── utils/

4. Adding New Components

New Panel (QDockWidget)

1. •Create header: include/kalahari/gui/panels/my_panel.h
2. •Create source: src/gui/panels/my_panel.cpp
3. •Inherit from QDockWidget
4. •Register in MainWindow::createDockWidgets()
5. •Add to CMakeLists.txt

New Dialog (QDialog)

1. •Create header: include/kalahari/gui/my_dialog.h
2. •Create source: src/gui/my_dialog.cpp
3. •Inherit from QDialog
4. •Add action in MainWindow or menu
5. •Add to CMakeLists.txt

New Widget (QWidget)

1. •Create header: include/kalahari/gui/my_widget.h
2. •Create source: src/gui/my_widget.cpp
3. •Inherit from QWidget
4. •Use in panel or dialog
5. •Add to CMakeLists.txt

New Core Class

1. •Create header: include/kalahari/core/my_class.h
2. •Create source: src/core/my_class.cpp
3. •Use kalahari::core namespace
4. •Add to CMakeLists.txt

5. Signal/Slot Connections

Theme changes

connect(&core::ThemeManager::getInstance(), &core::ThemeManager::themeChanged,
        this, &MyClass::onThemeChanged);

Icon/color changes

connect(&core::ArtProvider::getInstance(), &core::ArtProvider::resourcesChanged,
        this, &MyClass::onResourcesChanged);

6. File Naming

7. CMakeLists.txt Integration

set(KALAHARI_GUI_SOURCES
    ...
    src/gui/my_new_file.cpp
)

set(KALAHARI_GUI_HEADERS
    ...
    include/kalahari/gui/my_new_file.h
)

8. Analyzing Existing Code

1. •get_symbols_overview("path/to/file.cpp") - see class structure
2. •find_symbol("ClassName") - find class definition
3. •find_referencing_symbols("ClassName") - find usages

Key files to check

• •main_window.cpp - thin orchestrator, coordinator creation
• •dock_coordinator.cpp - panel/dock widget patterns
• •document_coordinator.cpp - document lifecycle patterns
• •settings_dialog.cpp - dialog patterns
• •art_provider.cpp - icon/color handling
• •plugin_signature.cpp - Ed25519 verification patterns