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