# exs-lab/exs-lock architecture

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

- Interactive diagram: https://gitdiagram.com/exs-lab/exs-lock
- Repository: https://github.com/exs-lab/exs-lock

## Overview

exs-lock is a GTK3 session-lock application for Wayland. The user launches the CLI, which prepares and activates GtkSessionLock, captures each monitor’s background, and creates a lock surface per display. Each surface presents a configurable password entry, blurred wallpaper, and live date/time; password submission is checked through PAM, and successful authentication unlocks and closes the surfaces. The README also documents CSS customization and Exs-Shell settings integration. Configuration and screenshot implementation details are represented from the tree, but their source was not sampled.

Main entry points: [`exs_lock/cli/lock.py`](https://github.com/exs-lab/exs-lock/blob/main/exs_lock/cli/lock.py) (Lock command), [`exs_lock/modules/lock.py`](https://github.com/exs-lab/exs-lock/blob/main/exs_lock/modules/lock.py) (Lock screen), [`exs_lock/utils/css.py`](https://github.com/exs-lab/exs-lock/blob/main/exs_lock/utils/css.py) (Stylesheet loader), [`exs_lock/cli/__init__.py`](https://github.com/exs-lab/exs-lock/blob/main/exs_lock/cli/__init__.py) (CLI dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Launch and setup"]
  node_cli["CLI dispatcher<br/>[__init__.py]"]
  node_lock_command["Lock command<br/>[lock.py]"]
  node_application["Fabric application"]
end

subgraph group_surfaces["Lock surfaces"]
  node_lockscreen["Lock screen<br/>[lock.py]"]
  node_datetime["Date and time<br/>[clock.py]"]
end

subgraph group_helpers["Runtime utilities"]
  node_monitors["Monitor discovery<br/>[monitor.py]"]
  node_screenshot["Screenshot capture<br/>[screenshot.py]"]
  node_config["Config loader<br/>[config.py]"]
  node_blur["Image blur<br/>[img.py]"]
  node_thread["Thread helper<br/>[loop.py]"]
end

subgraph group_styling["Appearance"]
  node_css_loader["Stylesheet loader<br/>[css.py]"]
  node_styles["Lock styles"]
end

node_user(("Desktop user"))
node_session_lock["GtkSessionLock"]
node_desktop["Wayland display"]
node_settings["User settings"]
node_pam["PAM authentication"]
node_custom_css["User CSS"]
node_exs_shell["Exs-Shell settings"]

node_user -->|"runs"| node_cli
node_cli -->|"dispatches"| node_lock_command
node_lock_command -->|"creates"| node_application
node_lock_command -->|"loads styles"| node_css_loader
node_css_loader -->|"reads defaults"| node_styles
node_css_loader -->|"loads or creates"| node_custom_css
node_lock_command -->|"sets stylesheet"| node_application
node_lock_command -->|"prepares and locks"| node_session_lock
node_lock_command -->|"gets monitor data"| node_monitors
node_monitors -->|"queries displays"| node_desktop
node_lock_command -->|"captures backgrounds"| node_screenshot
node_screenshot -->|"captures display"| node_desktop
node_lock_command -->|"creates per monitor"| node_lockscreen
node_lockscreen -->|"registers surface"| node_session_lock
node_lockscreen -->|"reads options"| node_config
node_config -->|"reads"| node_settings
node_lockscreen -->|"blurs background"| node_blur
node_lockscreen -->|"embeds widget"| node_datetime
node_lockscreen -->|"runs authentication"| node_thread
node_lockscreen -->|"checks password"| node_pam
node_lockscreen -->|"unlocks on success"| node_session_lock
node_exs_shell -.->|"configures optionally"| node_settings

click node_cli "https://github.com/exs-lab/exs-lock/blob/main/exs_lock/cli/__init__.py"
click node_lock_command "https://github.com/exs-lab/exs-lock/blob/main/exs_lock/cli/lock.py"
click node_monitors "https://github.com/exs-lab/exs-lock/blob/main/exs_lock/utils/monitor.py"
click node_screenshot "https://github.com/exs-lab/exs-lock/blob/main/exs_lock/utils/screenshot.py"
click node_lockscreen "https://github.com/exs-lab/exs-lock/blob/main/exs_lock/modules/lock.py"
click node_config "https://github.com/exs-lab/exs-lock/blob/main/exs_lock/utils/config.py"
click node_blur "https://github.com/exs-lab/exs-lock/blob/main/exs_lock/utils/img.py"
click node_datetime "https://github.com/exs-lab/exs-lock/blob/main/exs_lock/modules/widgets/clock.py"
click node_thread "https://github.com/exs-lab/exs-lock/blob/main/exs_lock/utils/loop.py"
click node_css_loader "https://github.com/exs-lab/exs-lock/blob/main/exs_lock/utils/css.py"
click node_styles "https://github.com/exs-lab/exs-lock/tree/main/exs_lock/styles"

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_lock_command,node_application,node_user,node_settings,node_custom_css toneBlue
class node_lockscreen,node_datetime toneAmber
class node_monitors,node_screenshot,node_config,node_blur,node_thread toneMint
class node_css_loader,node_styles toneRose
class node_session_lock,node_desktop,node_pam,node_exs_shell toneIndigo
```

## Components

### Launch and setup

- [CLI dispatcher](https://github.com/exs-lab/exs-lock/blob/main/exs_lock/cli/__init__.py): `exs_lock/cli/__init__.py`
- [Lock command](https://github.com/exs-lab/exs-lock/blob/main/exs_lock/cli/lock.py): `exs_lock/cli/lock.py`
- **Fabric application**

### Lock surfaces

- [Lock screen](https://github.com/exs-lab/exs-lock/blob/main/exs_lock/modules/lock.py): `exs_lock/modules/lock.py`
- [Date and time](https://github.com/exs-lab/exs-lock/blob/main/exs_lock/modules/widgets/clock.py): `exs_lock/modules/widgets/clock.py`

### Runtime utilities

- [Monitor discovery](https://github.com/exs-lab/exs-lock/blob/main/exs_lock/utils/monitor.py): `exs_lock/utils/monitor.py`
- [Screenshot capture](https://github.com/exs-lab/exs-lock/blob/main/exs_lock/utils/screenshot.py): `exs_lock/utils/screenshot.py`
- [Config loader](https://github.com/exs-lab/exs-lock/blob/main/exs_lock/utils/config.py): `exs_lock/utils/config.py`
- [Image blur](https://github.com/exs-lab/exs-lock/blob/main/exs_lock/utils/img.py): `exs_lock/utils/img.py`
- [Thread helper](https://github.com/exs-lab/exs-lock/blob/main/exs_lock/utils/loop.py): `exs_lock/utils/loop.py`

### Appearance

- [Stylesheet loader](https://github.com/exs-lab/exs-lock/blob/main/exs_lock/utils/css.py): `exs_lock/utils/css.py`
- [Lock styles](https://github.com/exs-lab/exs-lock/tree/main/exs_lock/styles): `exs_lock/styles`

### Other components

- **Desktop user**
- **GtkSessionLock**
- **Wayland display**
- **User settings**
- **PAM authentication**
- **User CSS**
- **Exs-Shell settings**

## Connections

- Desktop user → CLI dispatcher: runs
- CLI dispatcher → Lock command: dispatches
- Lock command → Fabric application: creates
- Lock command → Stylesheet loader: loads styles
- Stylesheet loader → Lock styles: reads defaults
- Stylesheet loader → User CSS: loads or creates
- Lock command → Fabric application: sets stylesheet
- Lock command → GtkSessionLock: prepares and locks
- Lock command → Monitor discovery: gets monitor data
- Monitor discovery → Wayland display: queries displays
- Lock command → Screenshot capture: captures backgrounds
- Screenshot capture → Wayland display: captures display
- Lock command → Lock screen: creates per monitor
- Lock screen → GtkSessionLock: registers surface
- Lock screen → Config loader: reads options
- Config loader → User settings: reads
- Lock screen → Image blur: blurs background
- Lock screen → Date and time: embeds widget
- Lock screen → Thread helper: runs authentication
- Lock screen → PAM authentication: checks password
- Lock screen → GtkSessionLock: unlocks on success
- Exs-Shell settings → User settings: configures optionally