# suratlayek/align-view architecture

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

- Interactive diagram: https://gitdiagram.com/suratlayek/align-view
- Repository: https://github.com/suratlayek/align-view

## Overview

1. **Project type**
   - This is a **Python desktop application** built around **Qt/PyQt5**.
   - Its purpose is to display a **semi-transparent image overlay** on top of the user’s screen for tracing, alignment, and comparison work.

2. **Entry point and application bootstrap**
   - `align_view.py` is the **main runtime entry point**.
   - It is the place where the Qt application is started, the main window/overlay is created, and the UI is wired to behavior.
   - For an architecture diagram, treat this as the **top-level orchestrator**.

3. **Main UI boundary**
   - `src/align_view_ui.py` is a **generated Python module** produced from the Qt Designer file.
   - `src/resources/align_view_ui.ui` is the **source-of-truth UI layout**.
   - The UI boundary is separated from runtime logic: layout comes from the generated UI file, while interaction logic lives in the main Python code.

4. **Overlay subsystem**
   - The core functional subsystem is the **overlay window** itself.
   - It supports:
     - image display
     - opacity control
     - scaling/zoom
     - rotation
     - moving/dragging
     - lock/unlock behavior
   - This is the primary “canvas” component and the main thing the user interacts with.

5. **Input and interaction flow**
   - The overlay responds to **mouse** and **keyboard** input directly:
     - drag to move
     - wheel to zoom
     - modified wheel gestures for rotation and opacity
     - arrow-key nudging for pixel-level positioning
   - Right-click exposes help/shortcut behavior.
   - These interactions are likely handled in the app logic layer and update the overlay state in real time.

6. **Image loading boundary**
   - The app accepts images as the content being overlaid.
   - README indicates **drag-and-drop image loading** is supported, so file input is an important boundary between the OS file system and the overlay logic.
   - The app is therefore not a generic editor; it is a **single-image overlay tool** with live transformation controls.

7. **Styling and visual assets**
   - `src/resources/adaptic.qss` is the Qt stylesheet used for the app’s visual theme.
   - `src/resources_rc.py` is the compiled Qt resource module that packages non-code assets into the app.
   - `src/resources/resources.qrc` defines those packaged assets.
   - This makes the UI presentation layer mostly self-contained and Qt-native.

8. **Generated vs. hand-authored code boundary**
   - A key architectural boundary is between:
     - **hand-authored runtime code**: `align_view.py`
     - **generated UI/resource code**: `src/align_view_ui.py`, `src/resources_rc.py`
   - That separation matters because UI changes are done in Qt Designer / resource files and then recompiled into Python.

9. **Packaging and dependency layer**
   - `requirements.txt` defines the Python dependencies, which are centered on Qt and related runtime packages.
   - The README also references a Windows installer release, so the project is designed to be distributable as a desktop app, not just run from source.

10. **Ancillary files**
   - `index.html` is present alongside the Python app; it is likely a static asset or distribution-related page rather than part of the core runtime path.
   - `LICENSE` and `.gitignore` are repository infrastructure, not functional subsystems.

11. **Overall runtime data flow**
   - User launches `align_view.py` → Qt application initializes → generated UI and Qt resources are loaded → user opens or drops an image → the image is drawn in the overlay window → mouse/keyboard input updates transform state (position, scale, rotation, opacity) → the overlay is redrawn continuously.
   - The app is essentially a **single-process GUI tool** with no obvious backend, database, or network service.

12. **How to draw the architecture**
   - The diagram should have one main desktop app boundary containing:
     - the bootstrap script
     - the overlay/window UI
     - input handling
     - image transform state
     - Qt-generated UI/resource assets
   - Outside the app boundary, show the **operating system** as the source of mouse/keyboard/file-drop events and screen surface rendering.

Main entry points: [`align_view.py`](https://github.com/suratlayek/align-view/blob/main/align_view.py) (align_view.py), [`src/align_view_ui.py`](https://github.com/suratlayek/align-view/blob/main/src/align_view_ui.py) (align_view_ui.py), [`src/resources_rc.py`](https://github.com/suratlayek/align-view/blob/main/src/resources_rc.py) (resources_rc.py), [`src/resources/align_view_ui.ui`](https://github.com/suratlayek/align-view/blob/main/src/resources/align_view_ui.ui) (align_view_ui.ui)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop App"]
  node_bootstrap["align_view.py<br/>runtime entrypoint<br/>[align_view.py]"]
  node_overlay["Overlay Window<br/>main canvas"]
  node_state{{"Transform State<br/>view state"}}
  node_input["Input Handler<br/>interaction logic"]
  node_loader["Image Loader<br/>file boundary"]
  node_ui_gen["align_view_ui.py<br/>generated Qt UI<br/>[align_view_ui.py]"]
  node_ui_src["align_view_ui.ui<br/>Qt Designer form<br/>[align_view_ui.ui]"]
  node_style["adaptic.qss<br/>Qt stylesheet<br/>[adaptic.qss]"]
  node_qrc["resources.qrc<br/>resource manifest<br/>[resources.qrc]"]
  node_rc_py["resources_rc.py<br/>generated resources<br/>[resources_rc.py]"]
end

subgraph group_external["Operating System"]
  node_os_input(("Mouse & Keys<br/>os input"))
  node_os_files["Dropped Files<br/>os file system"]
  node_display["Screen<br/>os display"]
end

node_bootstrap -->|"loads UI"| node_ui_gen
node_bootstrap -->|"loads assets"| node_rc_py
node_bootstrap -->|"creates"| node_overlay
node_bootstrap -->|"wires"| node_input
node_bootstrap -->|"applies theme"| node_style
node_ui_src -.->|"compiled to"| node_ui_gen
node_qrc -.->|"compiled to"| node_rc_py
node_input -->|"updates"| node_state
node_state -->|"drives view"| node_overlay
node_loader -->|"sets image"| node_overlay
node_os_input -->|"events"| node_input
node_os_files -->|"drop/open"| node_loader
node_overlay -->|"renders on"| node_display
node_ui_gen -->|"defines controls"| node_overlay
node_rc_py -->|"provides assets"| node_overlay

click node_bootstrap "https://github.com/suratlayek/align-view/blob/main/align_view.py"
click node_ui_gen "https://github.com/suratlayek/align-view/blob/main/src/align_view_ui.py"
click node_ui_src "https://github.com/suratlayek/align-view/blob/main/src/resources/align_view_ui.ui"
click node_style "https://github.com/suratlayek/align-view/blob/main/src/resources/adaptic.qss"
click node_qrc "https://github.com/suratlayek/align-view/blob/main/src/resources/resources.qrc"
click node_rc_py "https://github.com/suratlayek/align-view/blob/main/src/resources_rc.py"

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_bootstrap,node_overlay,node_state,node_input,node_loader,node_ui_gen,node_ui_src,node_style,node_qrc,node_rc_py toneBlue
class node_os_input,node_os_files,node_display toneAmber
```

## Components

### Desktop App

Core single-process Qt application

- [align_view.py](https://github.com/suratlayek/align-view/blob/main/align_view.py): runtime entrypoint · Starts Qt, builds the overlay, and wires the app together · `align_view.py`
- **Overlay Window**: main canvas · Semi-transparent floating image overlay shown on screen
- **Transform State**: view state · Tracks position, zoom, rotation, opacity, and lock state
- **Input Handler**: interaction logic · Handles mouse, wheel, keyboard, and shortcut behavior
- **Image Loader**: file boundary · Accepts opened or dropped images and feeds the overlay
- [align_view_ui.py](https://github.com/suratlayek/align-view/blob/main/src/align_view_ui.py): generated Qt UI · Python form generated from Qt Designer layout · `src/align_view_ui.py`
- [align_view_ui.ui](https://github.com/suratlayek/align-view/blob/main/src/resources/align_view_ui.ui): Qt Designer form · Source UI layout edited in Qt Designer · `src/resources/align_view_ui.ui`
- [adaptic.qss](https://github.com/suratlayek/align-view/blob/main/src/resources/adaptic.qss): Qt stylesheet · Defines the app’s visual theme and widget styling · `src/resources/adaptic.qss`
- [resources.qrc](https://github.com/suratlayek/align-view/blob/main/src/resources/resources.qrc): resource manifest · Declares packaged Qt assets for compilation · `src/resources/resources.qrc`
- [resources_rc.py](https://github.com/suratlayek/align-view/blob/main/src/resources_rc.py): generated resources · Compiled Qt resource module used at runtime · `src/resources_rc.py`

### Operating System

OS-provided input, files, and display surface

- **Mouse & Keys**: os input · System events used for dragging, zooming, rotation, and nudging
- **Dropped Files**: os file system · Dragged-in image files from the desktop or file manager
- **Screen**: os display · The desktop surface where the overlay is rendered

## Connections

- align_view.py → align_view_ui.py: loads UI · Bootstraps the generated Qt form into the app
- align_view.py → resources_rc.py: loads assets · Registers packaged Qt resources at startup
- align_view.py → Overlay Window: creates · Constructs the main overlay window
- align_view.py → Input Handler: wires · Connects UI actions and event handlers
- align_view.py → adaptic.qss: applies theme · Loads the Qt stylesheet for presentation
- align_view_ui.ui → align_view_ui.py: compiled to · Designer form is converted into the runtime Python UI module
- resources.qrc → resources_rc.py: compiled to · Qt resource manifest is compiled into the Python resource module
- Input Handler → Transform State: updates · Mouse and keyboard gestures mutate overlay transform state
- Transform State → Overlay Window: drives view · State changes are reflected in the rendered overlay
- Image Loader → Overlay Window: sets image · Loaded image content becomes the overlay’s canvas
- Mouse & Keys → Input Handler: events · Mouse, wheel, keyboard, and shortcut input enters from the OS
- Dropped Files → Image Loader: drop/open · Image files are provided through drag-and-drop or file selection
- Overlay Window → Screen: renders on · Overlay is drawn onto the desktop screen surface
- align_view_ui.py → Overlay Window: defines controls · Generated widgets provide the UI boundary for the overlay window
- resources_rc.py → Overlay Window: provides assets · Runtime resource module supplies packaged icons and assets