Note: This is a replacement for RFC #2529

**### RFC: Flameshot Plugin System Architecture
Status: Draft • Date: 2025-05-22 • Version: 0.1

1. Introduction

Flameshot requires a scalable plugin framework to enable modular extensions, empower user customization, and future-proof the application against evolving requirements. This RFC outlines the architectural design for a plugin system that balances flexibility, security, and performance.

2. Directory Structure

Plugins are organized under the user's configuration directory with a standardized naming convention:

~/.config/flameshot/
├── flameshot.ini              # Global configuration
└── plugins/                   # Plugin root directory
    └── {namespace}/           # Reverse-domain namespace (e.g., com.pub1)
        └── {plugin-id}/       # Unique plugin identifier
            ├── {plugin-id}.so # Shared library (C++ plugins)
            ├── {plugin-id}.py # Python script (Python plugins)
            ├── icon.svg       # Plugin icon (128x128 SVG)
            └── metadata.yaml  # Mandatory metadata

3. Plugin Configuration Model

3.1 Self-Managed Settings

Plugins have full autonomy over their internal configuration storage (e.g., INI files, JSON, databases). The core framework only mandates system-level metadata in metadata.yaml.

3.2 Standardized Metadata

global:
  name: "Watermark"            # Unique plugin ID
  type: "qt"                   # Plugin type (qt|python|binary)
  file: "libWatermark.so"      # Plugin binary/script
  version: "1.0.0"             # Semantic version
  author: "Developer Name"
metadata_fields:
  Watermark:
    type: str 
    description: "Path to watermark image"
    required: true
  Bottom:
    type: str 
    description: "Path to bottom overlay image"
    required: false
  PrintBG:
    type: str 
    description: "Path to background image for print mode"
  ColorBG:
    type: color
    description: "Background color when no image is specified (hex format)"
  PrintBG:
      type: subsection
      Frame:
          type: subsection
          Width:
            type: int 
            description: "Width of the print background frame"
            default: 3344                                                                                                                                                                                                                      
default_config:
  Watermark: "WM/Watermark.png"
  Bottom: "WM/Bottom.png"
  PrintBG: "WM/PrintBG.png"
  ColorBG: "#ffffff"
  PrintBG.Frame.Width: 3344

4. Process-Driven Execution Model

4.1 Configurable Workflows

Users can define custom processing pipelines for action/final_action plugins (e.g., upload, OCR). Pipelines specify:

• Plugin execution order
• Data transformation steps
• Conditional logic and error handling

4.2 Key Principles

1. Strict Protocol Adherence: Plugins execute in predefined sequences with standardized data passing.
2. Dynamic Reordering: Workflows support conditional steps based on runtime conditions.
3. Metadata Propagation: Plugins can modify both the image (QPixmap) and metadata (e.g., file format).

5. Interoperability Architecture

5.1 Bidirectional Communication

A layered model enables secure interaction between plugins and the core:

graph LR  
    A[Plugin A] -->|Request| B(Core API)  
    B -->|Response| A  
    C[Plugin B] -->|Request| B  
    B -->|Response| C  
    B -->|Event Trigger| D{Event Bus}  
    D -->|Broadcast| A  
    D -->|Broadcast| C  

5.2 Core Components

1. Core API Surface: Exposes controlled access to screenshot data, configuration, and events.
2. Communication Channels: Defines synchronous (method calls) and asynchronous (events) interaction patterns.

6. Security & Compatibility

1. Access Control: Plugins operate within a sandbox with restricted file system and network access.
2. Versioning: Semantic versioning ensures API backward compatibility.
3. Validation: Metadata schema validation prevents misconfiguration.

7. Core API

7.1 Plugin API

1. stdcall bool Initialization(int resource);
2. stdcall bool Deinitialization(int resource);
3. stdcall bool DeinitializationAll();
4. stdcall struct ResourcreInstance *RequestResource(int resource);

8. References

• Qt Plugin Architecture: https://doc.qt.io/qt-6/plugins-howto.html
• XDG Base Directory Specification: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
• Convention_over_configuration: https://en.wikipedia.org/wiki/Convention_over_configuration

Change Log:

• 2025-05-22: Initial draft
• [Future]: Incorporate community feedback **