# artemsen/swayimg architecture

> Architecture diagram of the GitHub repository artemsen/swayimg, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/artemsen/swayimg
- Repository: https://github.com/artemsen/swayimg

## Overview

Swayimg is a customizable image viewer for Wayland and DRM. Its principal workflow accepts file, pipe, or command output; maintains an image list; decodes supported image and preview formats; then displays content in viewer or gallery mode, with slideshow and animation support. Lua configuration exposes application controls, and Wayland/DRM provide output backends. The graph follows the visible application initialization and Lua configuration excerpts plus README capabilities; many format and rendering internals were not sampled, so those relationships are documented at subsystem level.

Main entry points: [`src/application.cpp`](https://github.com/artemsen/swayimg/blob/master/src/application.cpp) (Application loop), [`src/luaengine.cpp`](https://github.com/artemsen/swayimg/blob/master/src/luaengine.cpp) (Lua engine), [`src/render.cpp`](https://github.com/artemsen/swayimg/blob/master/src/render.cpp) (Rendering), [`src/viewer.cpp`](https://github.com/artemsen/swayimg/blob/master/src/viewer.cpp) (Viewer mode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and events"]
  node_cli["Command line<br/>[main.cpp]"]
  node_application["Application loop<br/>[application.cpp]"]
  node_events["File/event monitoring<br/>[fsmonitor.cpp]"]
end

subgraph group_content["Image content"]
  node_image_list["Image list<br/>[imagelist.cpp]"]
  node_image["Image model<br/>[image.hpp]"]
  node_format_factory["Format factory<br/>[formatfactory.cpp]"]
  node_format_decoders["Format decoders"]
  node_font_preview["Font preview<br/>[font.cpp]"]
  node_video_preview["Video storyboard<br/>[video.cpp]"]
end

subgraph group_modes["Viewing modes"]
  node_viewer["Viewer mode<br/>[viewer.cpp]"]
  node_gallery["Gallery mode<br/>[gallery.cpp]"]
  node_slideshow["Slideshow<br/>[slideshow.cpp]"]
end

subgraph group_presentation["Presentation"]
  node_renderer["Rendering<br/>[render.cpp]"]
  node_wayland["Wayland output<br/>[ui_wayland.cpp]"]
  node_drm["DRM output<br/>[ui_drm.cpp]"]
end

subgraph group_scripting["Scripting"]
  node_lua["Lua engine<br/>[luaengine.cpp]"]
  node_lua_bridge["Lua bindings<br/>[Namespace.h]"]
end

node_user(("Viewer user"))

node_user -->|"starts viewer"| node_cli
node_cli -.->|"starts app"| node_application
node_application -->|"initializes config"| node_lua
node_application -->|"initializes monitor"| node_events
node_application -->|"initializes list"| node_image_list
node_application -->|"selects backend"| node_wayland
node_application -.->|"selects backend"| node_drm
node_image_list -.->|"holds entries"| node_image
node_format_factory -.->|"dispatches decoding"| node_format_decoders
node_format_decoders -.->|"produces images"| node_image
node_font_preview -.->|"provides preview"| node_image
node_video_preview -->|"provides storyboard"| node_image
node_application -->|"activates mode"| node_viewer
node_application -->|"initializes mode"| node_gallery
node_viewer -.->|"renders content"| node_renderer
node_gallery -.->|"renders thumbnails"| node_renderer
node_slideshow -->|"advances images"| node_viewer
node_renderer -.->|"draws output"| node_wayland
node_renderer -.->|"draws output"| node_drm
node_lua -.->|"registers API"| node_lua_bridge
node_lua -->|"configures formats"| node_format_factory
node_lua -->|"configures list"| node_image_list
node_lua -->|"controls gallery"| node_gallery
node_lua -->|"controls viewer"| node_viewer

click node_cli "https://github.com/artemsen/swayimg/blob/master/src/main.cpp"
click node_application "https://github.com/artemsen/swayimg/blob/master/src/application.cpp"
click node_events "https://github.com/artemsen/swayimg/blob/master/src/fsmonitor.cpp"
click node_image_list "https://github.com/artemsen/swayimg/blob/master/src/imagelist.cpp"
click node_image "https://github.com/artemsen/swayimg/blob/master/src/image.hpp"
click node_format_factory "https://github.com/artemsen/swayimg/blob/master/src/formatfactory.cpp"
click node_format_decoders "https://github.com/artemsen/swayimg/tree/master/src/formats"
click node_font_preview "https://github.com/artemsen/swayimg/blob/master/src/font.cpp"
click node_video_preview "https://github.com/artemsen/swayimg/blob/master/src/formats/video.cpp"
click node_viewer "https://github.com/artemsen/swayimg/blob/master/src/viewer.cpp"
click node_gallery "https://github.com/artemsen/swayimg/blob/master/src/gallery.cpp"
click node_slideshow "https://github.com/artemsen/swayimg/blob/master/src/slideshow.cpp"
click node_renderer "https://github.com/artemsen/swayimg/blob/master/src/render.cpp"
click node_wayland "https://github.com/artemsen/swayimg/blob/master/src/ui_wayland.cpp"
click node_drm "https://github.com/artemsen/swayimg/blob/master/src/ui_drm.cpp"
click node_lua "https://github.com/artemsen/swayimg/blob/master/src/luaengine.cpp"
click node_lua_bridge "https://github.com/artemsen/swayimg/blob/master/src/external/luabridge/detail/Namespace.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_application,node_events,node_user toneBlue
class node_image_list,node_image,node_format_factory,node_format_decoders,node_font_preview,node_video_preview toneAmber
class node_viewer,node_gallery,node_slideshow toneMint
class node_renderer,node_wayland,node_drm toneRose
class node_lua,node_lua_bridge toneIndigo
```

## Components

### Startup and events

- [Command line](https://github.com/artemsen/swayimg/blob/master/src/main.cpp): `src/main.cpp`
- [Application loop](https://github.com/artemsen/swayimg/blob/master/src/application.cpp): `src/application.cpp`
- [File/event monitoring](https://github.com/artemsen/swayimg/blob/master/src/fsmonitor.cpp): `src/fsmonitor.cpp`

### Image content

- [Image list](https://github.com/artemsen/swayimg/blob/master/src/imagelist.cpp): `src/imagelist.cpp`
- [Image model](https://github.com/artemsen/swayimg/blob/master/src/image.hpp): `src/image.hpp`
- [Format factory](https://github.com/artemsen/swayimg/blob/master/src/formatfactory.cpp): `src/formatfactory.cpp`
- [Format decoders](https://github.com/artemsen/swayimg/tree/master/src/formats): `src/formats`
- [Font preview](https://github.com/artemsen/swayimg/blob/master/src/font.cpp): `src/font.cpp`
- [Video storyboard](https://github.com/artemsen/swayimg/blob/master/src/formats/video.cpp): `src/formats/video.cpp`

### Viewing modes

- [Viewer mode](https://github.com/artemsen/swayimg/blob/master/src/viewer.cpp): `src/viewer.cpp`
- [Gallery mode](https://github.com/artemsen/swayimg/blob/master/src/gallery.cpp): `src/gallery.cpp`
- [Slideshow](https://github.com/artemsen/swayimg/blob/master/src/slideshow.cpp): `src/slideshow.cpp`

### Presentation

- [Rendering](https://github.com/artemsen/swayimg/blob/master/src/render.cpp): `src/render.cpp`
- [Wayland output](https://github.com/artemsen/swayimg/blob/master/src/ui_wayland.cpp): `src/ui_wayland.cpp`
- [DRM output](https://github.com/artemsen/swayimg/blob/master/src/ui_drm.cpp): `src/ui_drm.cpp`

### Scripting

- [Lua engine](https://github.com/artemsen/swayimg/blob/master/src/luaengine.cpp): `src/luaengine.cpp`
- [Lua bindings](https://github.com/artemsen/swayimg/blob/master/src/external/luabridge/detail/Namespace.h): `src/external/luabridge/detail/Namespace.h`

### Other components

- **Viewer user**

## Connections

- Viewer user → Command line: starts viewer (evidence: `README.md`)
- Command line → Application loop: starts app
- Application loop → Lua engine: initializes config (evidence: `src/application.cpp`)
- Application loop → File/event monitoring: initializes monitor (evidence: `src/application.cpp`)
- Application loop → Image list: initializes list (evidence: `src/application.cpp`)
- Application loop → Wayland output: selects backend (evidence: `src/application.cpp`)
- Application loop → DRM output: selects backend
- Image list → Image model: holds entries
- Format factory → Format decoders: dispatches decoding
- Format decoders → Image model: produces images
- Font preview → Image model: provides preview
- Video storyboard → Image model: provides storyboard (evidence: `README.md`)
- Application loop → Viewer mode: activates mode (evidence: `src/application.cpp`)
- Application loop → Gallery mode: initializes mode (evidence: `src/application.cpp`)
- Viewer mode → Rendering: renders content
- Gallery mode → Rendering: renders thumbnails
- Slideshow → Viewer mode: advances images (evidence: `README.md`)
- Rendering → Wayland output: draws output
- Rendering → DRM output: draws output
- Lua engine → Lua bindings: registers API
- Lua engine → Format factory: configures formats (evidence: `src/luaengine.cpp`)
- Lua engine → Image list: configures list (evidence: `src/luaengine.cpp`)
- Lua engine → Gallery mode: controls gallery (evidence: `src/luaengine.cpp`)
- Lua engine → Viewer mode: controls viewer (evidence: `src/luaengine.cpp`)