# kde/ghostwriter architecture

> Architecture diagram of the GitHub repository kde/ghostwriter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kde/ghostwriter
- Repository: https://github.com/kde/ghostwriter

## Overview

##### Main components in the system
- GUI / Frontend Layer:
– MainWindow (src/mainwindow.cpp/h) assembling the visual components.
– Editor component (src/editor/) that handles the text editing, syntax highlighting, and state management.
– Preview pane (src/preview/) which renders the live HTML preview using either Qt’s web components (e.g., QWebEngineView) or a sandboxed webpage.
– Sidebar and auxiliary UI widgets (src/sidebar.cpp, src/timelabel.cpp).
– Menu actions and command components (src/appactions and UI dialogs under src/settings).

- Business & Application Layer:
– Document Manager (src/documentmanager) managing open documents and files.
– Markdown processor integration (src/markdown/) that integrates cmark-gfm (and optionally Pandoc or MultiMarkdown, auto-detected at runtime).
– Export functionality (src/export/) that interacts with the Markdown processor to produce files in different formats.
– Spell Checking module (src/spelling/) to handle real-time spell checking.
– Statistics and Logging modules (src/statistics/ and src/logging.*) for performance metrics and error logging.

- Integration & Dependencies:
– Third-Party Libraries: 3rdparty directory includes dependencies like MathJax for math rendering, cmark-gfm for Markdown processing, and React (perhaps for specialized parsing or dynamic content modules).
– Build and CI tools: CMake configuration (CMakeLists.txt in various directories, build system integration in .github and .gitlab-ci.yml), testing folders (autotest/), and packaging files (such as snapcraft.yaml).

##### Relationships and interactions
- User actions (typing/editing, invoking preview/export) occur in the GUI layer.
- The Document Manager receives these UI events, updates the internal document model, and forward the content to the Markdown Processing module.
- The Markdown processor (using cmark-gfm and possibly other Markdown processors auto-detected at startup) converts the text to HTML.
- The Preview module receives the processed HTML and renders it within a sandboxed webpage.
- The Exporter module can also invoke the Markdown processing to produce output in different formats.
- Settings and Theme modules supply configuration to the GUI and core modules at startup, and changing them propagates new appearance settings to the Editor and Preview.
- Spellchecking services monitor the text input and interact (via decorators) with the editing widget layers.
- Logging and statistics monitor user activity, errors, and provide diagnostics that may be shown on-screen or saved.
- CI/build modules trigger automated tests and build pipelines as defined in the repository’s various config files.

##### Architectural Patterns
- Layered Architecture: The overall structure is layered (UI -> Business Logic -> Integration/Third-Party Dependencies) which allows for clear separation of concerns.
- Modular design: Each major functionality (editor, export, markdown processing, settings, theming) is contained within its own module directory that may communicate via defined interfaces.
- Extensibility: The use of external Markdown processors and the auto-detection of optional tools (Pandoc, MultiMarkdown, cmark) show that the design allows integration with external libraries.

##### Relevant technologies, frameworks, and libraries
- Qt (likely Qt 6 even though there is mention of potential issues on Windows, with backward compatibility to Qt 5).
- C++ and CMake for core application development and building.
- Third-party libraries such as cmark-gfm (Markdown processor), MathJax (for math rendering), and some React components (possibly for interactive preview or help sections).
- CI and version control integrations: Git, GitHub/GitLab workflows, and build automation scripts.

- Clear labels for each identified module (e.g., “Editor Component”, “Markdown Processor”, “Document Manager”, “Preview Pane”, “Export Module”, “Spellchecker”, “Theme Manager”, “Settings”, “Third-Party Libraries”).
– Core application modules.
– UI components.
– External dependencies.
– Build/CI components.
- Ancillary components such as logging/statistics to show diagnostics and monitoring across the system.

## Diagram (Mermaid)

```mermaid
graph TB
    %% GUI / Frontend Layer
    subgraph "GUI / Frontend Layer"
        GUI1["MainWindow"]:::gui
        GUI2["Editor Component"]:::gui
        GUI3["Preview Pane"]:::gui
        GUI4["Sidebar & Auxiliary UI Widgets"]:::gui
        GUI5["Menu Actions & UI Dialogs"]:::gui
    end

    %% Business & Application Layer
    subgraph "Business & Application Layer"
        BUS1["Document Manager"]:::business
        BUS2["Markdown Processor Integration"]:::business
        BUS3["Export Functionality"]:::business
        BUS4["Spell Checking Module"]:::business
        BUS5["Theme Management & Settings"]:::business
        BUS6["Statistics and Logging"]:::business
    end

    %% Integration & Dependencies
    subgraph "Integration & Dependencies"
        INT1["Third-Party Libraries"]:::integration
        INT2["Build and CI Tools"]:::integration
    end

    %% Connections: GUI Layer to Business Layer
    GUI2 -->|"sendUpdate"| BUS1
    BUS1 -->|"processMarkdown"| BUS2
    BUS2 -->|"convertToHTML"| GUI3
    BUS2 -->|"exportFormat"| BUS3
    GUI2 -->|"spellcheck"| BUS4

    %% Theme Management influences GUI components
    BUS5 -->|"applyTheme"| GUI2
    BUS5 -->|"applyTheme"| GUI3
    GUI5 -->|"updateSettings"| BUS5

    %% Logging connections
    BUS1 -->|"logActivity"| BUS6
    BUS5 -->|"logSettings"| BUS6

    %% Integration feeds into Business and GUI
    INT1 -->|"provideLibs"| BUS2
    INT1 -->|"provideJSRender"| GUI3
    INT2 -->|"buildTest"| BUS1

    %% Styling
    classDef gui fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef business fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef integration fill:#ffeeba,stroke:#856404,stroke-width:2px;

    %% Click Events
    click GUI1 "https://github.com/kde/ghostwriter/blob/master/src/mainwindow.cpp"
    click GUI2 "https://github.com/kde/ghostwriter/tree/master/src/editor/"
    click GUI3 "https://github.com/kde/ghostwriter/tree/master/src/preview/"
    click GUI4 "https://github.com/kde/ghostwriter/blob/master/src/sidebar.cpp"
    click GUI5 "https://github.com/kde/ghostwriter/blob/master/src/appactions.cpp"
    click BUS1 "https://github.com/kde/ghostwriter/blob/master/src/documentmanager.cpp"
    click BUS2 "https://github.com/kde/ghostwriter/tree/master/src/markdown/"
    click BUS3 "https://github.com/kde/ghostwriter/tree/master/src/export/"
    click BUS4 "https://github.com/kde/ghostwriter/tree/master/src/spelling/"
    click BUS5 "https://github.com/kde/ghostwriter/tree/master/src/theme/"
    click BUS6 "https://github.com/kde/ghostwriter/tree/master/src/statistics/"
    click INT1 "https://github.com/kde/ghostwriter/tree/master/3rdparty/"
    click INT2 "https://github.com/kde/ghostwriter/blob/master/CMakeLists.txt"
```
