# darktable-org/darktable architecture

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

- Interactive diagram: https://gitdiagram.com/darktable-org/darktable
- Repository: https://github.com/darktable-org/darktable

## Overview

##### Project Type and Purpose
- darktable is an open source photography workflow application. It manages raw files (digital negatives) using a database, provides a zoomable lighttable interface, and allows advanced non‐destructive editing through various image processing and enhancement modules.
- Its functionality spans raw image import/export, in-depth processing (via a series of “iop” modules), and a rich GUI based on GTK.

##### File Structure
- The top-level structure includes build and configuration files (CMakeLists.txt, cmake modules, build.sh), documentation (doc/ and packaging/ directories), source code (src/), tests (src/tests), and external libraries/submodules (src/external).
- The “src” directory is split into many components reflecting different application layers:
– Core engine and common functionality under src/common
– Image processing modules under src/iop (for operations such as demosaicing, noise reduction, tone curve adjustments, etc.)
– User interface components under src/gui and dtgtk (GTK-based GUI toolkit components)
– Scripting and extension support in src/lua (for Lua API and scripting integration)
– Command-line tools in src/cli, as well as specialized utilities (e.g., src/generate-cache)
- There is a clear separation between development modules (src/develop), libraries (src/libs), image I/O formats (src/imageio), and tests (src/tests).

##### Extract Insights from the README
- The README highlights that darktable is a photographer’s tool – a virtual lighttable/darkroom – and it emphasizes both editing capabilities and integration of various external libraries (e.g., Exiv2, LibRaw, Lensfun, OpenCL, OpenMP, Lua).
- It explains the process of building, installing, and even testing a development snapshot – indicating that the design must accommodate flexible configuration and dependency injection.

##### Main Components and Their Relationships
a. User Interface Layer:
- GUI Module (src/gui, dtgtk) using GTK.
- CLI Tool and Lighttable/Darkroom view.
b. Core Processing Engine:
- Image processing pipeline modules communicate internally, where a “control” system (src/control) manages settings, signals, and progress.
c. Database and Data Management:
- Components handling image metadata, processing history, and the digital negatives’ database (e.g., src/common/database.c and various caching modules).
d. Plugin and Extension System:
- Lua integration (src/lua) provides extensibility to add plugins and scripting features.
e. Integration with External Dependencies:
- External libraries (LibRaw, Exiv2, Lensfun, OpenCL, OpenMP, etc.) are invoked from the core engine and image I/O modules.
- Packaging directories also indicate cross-platform support and integration with system-specific libraries (e.g., Windows, macOS, Linux packaging scripts).
f. Build and Testing Infrastructure:
- Multiple configuration and build scripts (CMake modules, build.sh, packaging/*) indicate the build system’s central role in compiling various modules.
- A dedicated test suite exists under src/tests for unit and integration testing.

##### Architectural Patterns and Design Principles
- Modular design: While darktable is a single application, the separation into clear modules (GUI, engine, I/O, testing, external scripts) suggests modularity.
- Pipeline architecture: The image processing tasks follow a pipeline (input > processing modules > output), which can be depicted with sequential flow.
- Plugin architecture: The Lua scripting integration provides points for extensibility.
- Separation between presentation (GUI views) and business logic (processing engine) adheres to principles similar to MVC even though it’s not formally MVC.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI1["GUI – dtgtk/GTK Interface"]:::ui
        UI4["GTK Toolkit (dtgtk)"]:::ui
        UI2["Lighttable/Darkroom View"]:::ui
        UI3["CLI Tool"]:::ui
    end

    %% Core Processing Engine
    subgraph "Core Processing Engine"
        CORE["Core Engine – common functions"]:::core
        IOP["IOP Modules – image processing pipeline"]:::core
        DEVELOP["Develop Modules – non-destructive editing"]:::core
    end

    %% Extension & Data Management
    subgraph "Extension & Data Management"
        DB["Database & Data Management"]:::database
        LUA["Lua Scripting – Plugin System"]:::plugin
    end

    %% External Dependencies
    subgraph "External Dependencies"
        EXT_LIBS["External Libraries (OpenCL, OpenMP, etc.)"]:::external
        IO_LIBS["Image I/O (LibRaw, Exiv2, etc.)"]:::external
    end

    %% Build & Testing Infrastructure
    subgraph "Build & Testing Infrastructure"
        BUILD["Build Infrastructure (CMake, build scripts)"]:::infrastructure
        TEST["Testing Framework"]:::infrastructure
        PACK["Packaging Scripts"]:::infrastructure
    end

    %% Connections between User Interface and Core Processing Engine
    UI1 -->|"commands"| CORE
    UI4 -->|"commands"| CORE
    UI2 -->|"commands"| CORE
    UI3 -->|"commands"| CORE

    %% Connections within Core Processing Engine
    CORE -->|"process"| IOP
    CORE -->|"edit"| DEVELOP
    CORE -->|"metadata"| DB
    CORE -->|"extend"| LUA

    %% Connections between UI and Plugin System
    UI1 -->|"script"| LUA

    %% Connections from Core Modules to External Dependencies
    IOP -->|"uses"| EXT_LIBS
    DEVELOP -->|"uses"| IO_LIBS

    %% Connections from Build & Testing Infrastructure to Core Components
    BUILD --- CORE
    BUILD --- UI1
    BUILD --- UI4
    BUILD --- DB
    TEST --- CORE
    PACK --- BUILD

    %% Click Events for Component Mapping
    click UI1 "https://github.com/darktable-org/darktable/tree/master/src/gui"
    click UI4 "https://github.com/darktable-org/darktable/tree/master/src/dtgtk"
    click UI2 "https://github.com/darktable-org/darktable/tree/master/src/views"
    click UI3 "https://github.com/darktable-org/darktable/tree/master/src/cli"
    click CORE "https://github.com/darktable-org/darktable/tree/master/src/common"
    click IOP "https://github.com/darktable-org/darktable/tree/master/src/iop"
    click DEVELOP "https://github.com/darktable-org/darktable/tree/master/src/develop"
    click DB "https://github.com/darktable-org/darktable/blob/master/src/common/database.c"
    click LUA "https://github.com/darktable-org/darktable/tree/master/src/lua"
    click EXT_LIBS "https://github.com/darktable-org/darktable/tree/master/src/external"
    click IO_LIBS "https://github.com/darktable-org/darktable/tree/master/src/imageio"
    click BUILD "https://github.com/darktable-org/darktable/blob/master/CMakeLists.txt"
    click TEST "https://github.com/darktable-org/darktable/tree/master/src/tests"
    click PACK "https://github.com/darktable-org/darktable/tree/master/packaging"

    %% Styles
    classDef ui fill:#FFDD57,stroke:#333,stroke-width:2;
    classDef core fill:#A1D490,stroke:#333,stroke-width:2;
    classDef database fill:#F78C6B,stroke:#333,stroke-width:2;
    classDef plugin fill:#FFB347,stroke:#333,stroke-width:2;
    classDef external fill:#AEDFF7,stroke:#333,stroke-width:2;
    classDef infrastructure fill:#D3A5F9,stroke:#333,stroke-width:2;
```
