# lkrapf/qutebrowser architecture

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

- Interactive diagram: https://gitdiagram.com/lkrapf/qutebrowser
- Repository: https://github.com/lkrapf/qutebrowser

## Overview

##### Main Components to Highlight
- User Interface (UI) Layer:
- Main window, status bar, prompt, tabbed browser, and other window components found in directories like “mainwindow”, “browser”, and “keyinput.”
- These components are responsible for rendering the minimal GUI, displaying pages, and handling key events.
- Command and Input Handling:
- Modules under “commands”, “completion”, “keyinput”, and “misc” manage parsing keystrokes, executing commands, and managing user input.
- This subsystem should be depicted as processing keyboard events and mapping them to user actions.
- Browser Engine / Rendering Backend:
- The project provides support for two potential backends: the QtWebEngine (preferred, built using Chromium) and the alternative, QtWebKit (present in “browser/webkit”).
- Separate the rendering engine layer to reflect how HTML, scripts, and other web content is processed.
- API & Extensions:
- The “api” and “extensions” directories contain modules for exposing the internal functionality (e.g. for userscripts and hooks) and allow customization (e.g. interceptors, configuration commands).
- As an abstraction layer that interacts both with the core browser functionalities and external extensions.
- Configuration & Scripting Subsystem:
- The configuration management is spread across “config” (for reading, caching, and initializing settings) and even some parts of “commands” if those relate to configuring aspects of the browser.
- This component manages settings loaded at startup and updated during runtime, influencing behavior across subsystems.
- Ancillary Components:
- Support modules like “utils” provide shared helper functions for logging, error handling, resource management, etc.
- External libraries and dependencies (e.g., PyQt, Jinja2, PyYAML) which the system relies on.
- Testing and Documentation:
- While not a part of the runtime architecture, the “tests”, “doc”, and “misc” directories should be mentioned in a side-note or as separate concerns to indicate the organization for quality assurance and documentation.

##### Relationships and Data Flow
- The main qutebrowser entry-point (qutebrowser.py) initializes the application and spawns the main UI loop.
- The UI layer interacts with the key input system that captures keyboard events.
- Key events are forwarded to the command parser and completion submodules to translate user input into actions.
- Command execution may trigger updates in the browser state (for navigation, history, bookmarks, etc.) and interact with the rendering layer.
- The rendering engine (either QtWebEngine or QtWebKit) retrieves and processes web content. The browser interacts with it for tasks like navigation, downloads, or displaying PDFs (with optional pdf.js integration).
- The configuration subsystem provides settings and preferences that are applied across the UI, command, and browser engine layers.
- API modules and extension points allow external scripts and hooks to influence the browser, often bridging between user commands and lower-level operations.

##### Architectural Patterns and Design Principles
- Dependency Inversion: Many core modules (like the API and configuration systems) are designed to be consumed by higher-level components (like the command engine or UI) and might be extended by plugins. Highlight these relationships.
- Layered Design: Represent a layered architecture where the front-end (UI) sits on top of core logic, which in turn interfaces with external systems (web rendering, network).

##### Putting It All Together
- qutebrowser.py → Initialization of the Main Window (UI) layer.
- UI layer captures key events → forwards to Key Input / Command Parser.
- Command Parser interacts with the Configuration System and API to execute commands.
- Commands update browser state, navigation, or interact with the Rendering Engine.
- The Rendering Engine (displaying web content) sends event-based feedback (like download notifications) back to the UI.
- Ancillary layers (like utilities and logging) span across these components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Entry["qutebrowser Entry Point"]:::entry

    subgraph "UI Layer"
        UI1["Main Window"]:::ui
        UI2["Browser Display"]:::ui
        UI3["Key Input Capture"]:::ui
    end

    subgraph "Command and Input Handling"
        CMD1["Command Parser"]:::command
        CMD2["Input Completion"]:::command
    end

    subgraph "Configuration & Scripting"
        CFG["Configuration System"]:::config
    end

    subgraph "Browser Engine / Rendering"
        ENG1["QtWebEngine"]:::engine
        ENG2["QtWebKit"]:::engine
    end

    subgraph "API & Extensions"
        API["API Module"]:::api
        EXT["Extensions"]:::api
    end

    subgraph "Ancillary Components"
        UTILS["Utilities & Helpers"]:::utils
    end

    subgraph "Testing & Documentation"
        TESTDOC["Testing & Documentation"]:::testing
    end

    Entry -->|"init"| UI1
    UI1 -->|"displays"| UI2
    UI3 -->|"captured"| CMD1
    UI3 -->|"captured"| CMD2
    CMD1 -->|"reads"| CFG
    CMD1 -->|"calls"| API
    API -->|"triggers"| EXT
    CMD1 -->|"navigates"| ENG1
    CMD1 -->|"navigates"| ENG2
    ENG1 -->|"renders"| UI2
    ENG2 -->|"renders"| UI2
    CFG -->|"updates"| UI1

    UTILS -.-> UI1
    UTILS -.-> CMD1
    UTILS -.-> ENG1
    UTILS -.-> API

    Entry -->|"QA_init"| TESTDOC

    click UI1 "https://github.com/lkrapf/qutebrowser/tree/master/qutebrowser/mainwindow"
    click UI2 "https://github.com/lkrapf/qutebrowser/tree/master/qutebrowser/browser"
    click UI3 "https://github.com/lkrapf/qutebrowser/tree/master/qutebrowser/keyinput"
    click CMD1 "https://github.com/lkrapf/qutebrowser/tree/master/qutebrowser/commands"
    click CMD2 "https://github.com/lkrapf/qutebrowser/tree/master/qutebrowser/completion"
    click ENG1 "https://github.com/lkrapf/qutebrowser/tree/master/qutebrowser/browser/webengine"
    click ENG2 "https://github.com/lkrapf/qutebrowser/tree/master/qutebrowser/browser/webkit"
    click API "https://github.com/lkrapf/qutebrowser/tree/master/qutebrowser/api"
    click EXT "https://github.com/lkrapf/qutebrowser/tree/master/qutebrowser/extensions"
    click CFG "https://github.com/lkrapf/qutebrowser/tree/master/qutebrowser/config"
    click UTILS "https://github.com/lkrapf/qutebrowser/tree/master/qutebrowser/utils"
    click TESTDOC "https://github.com/lkrapf/qutebrowser/tree/master/tests"

    classDef entry fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef ui fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef command fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef config fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef engine fill:#F5CBA7,stroke:#BA4A00,stroke-width:2px;
    classDef api fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef utils fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef testing fill:#F0F3F4,stroke:#7B7D7D,stroke-width:2px;
```
