# dynobo/normcap architecture

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

- Interactive diagram: https://gitdiagram.com/dynobo/normcap
- Repository: https://github.com/dynobo/normcap

## Overview

##### Main Components and Their Roles
- Entry Point & Application Initialization:
- normcap/__main__.py and normcap/app.py serve as the entry point and initialize the application.
- Graphical User Interface (GUI) Layer:
- normcap/gui – Handles windows, notifications, menus (system tray) and manages user interactions.
- Components such as language_manager, window, and menu_button represent sub-components responsible for localization, windowing, and interactive elements.
- Screenshot Capture Module:
- normcap/screengrab – Implements screen capture using various handlers (e.g., Qt, DBus portal, Grim on Linux).
- The control flow here is triggered by user actions (often via the tray or GUI).
- OCR Processing Pipeline:
- normcap/ocr – Contains modules for image enhancement, text recognition (via tesseract), and transformers (e.g., transformers/email_address.py, paragraph.py, etc.) that refine the OCR output.
- This module takes the captured image as input and processes it in sequential stages: enhancing the image, passing it to Tesseract, and then transforming the output into usable text.
- Clipboard Integration:
- normcap/clipboard – Manages interactions with the clipboard by using various handlers (such as qtclipboard, xclip, pbcopy, etc.) to either retrieve or send text data.
- External Dependencies:
- Interaction with external tools like Tesseract (run via command-line or Python bindings) and external utilities for clipboard (xclip, wl-clipboard).

##### Relationships and Control Flow Among Components
- The main entry (__main__.py) bootstraps the NormCap application by initializing the app module.
- UI Launch & User Interaction:
- User actions (like clicking a “Capture” button in the system tray or menu) initiate the capture process.
- Launching the Screen Capture:
- The GUI triggers functions in the normcap/screengrab module.
- Depending on the platform/handler, the capture module chooses an appropriate handler (e.g., dbus_portal, qt, or grim) based on the OS or user settings.
- Processing the Captured Image:
- Once an image is captured, the data flows from the screengrab module into the OCR pipeline.
- In the OCR processing module (normcap/ocr), the image might first be enhanced (normcap/ocr/enhance.py), then passed to Tesseract (normcap/ocr/tesseract.py), and finally processed by a series of transformers (such as the ones located in normcap/ocr/transformers) to extract and format text.
- Handling Text and Clipboard Operations:
- After text extraction, if the operation is intended to “capture information instead of images,” the text can be copied to the clipboard.
- Feedback to the User:

##### Architectural Patterns and Technologies to Highlight
- Modular Design – Each major application function is split into distinct directories (gui, screengrab, ocr, clipboard).
- Event-Driven and Reactive Flow – The control flow is primarily driven by user events (e.g., clicking items, system tray events) that propagate through the chosen modules.
- Clear Separation Between Presentation and Business Logic – The GUI layer (using PySide6) is distinct from the OCR processing and clipboard management.
- Cross-Platform Handling – The bundle and platforms directories (e.g., bundle/platforms/*.py) indicate that there is custom logic for handling differences among operating systems.
- Use of External CLI Tools – Integration with Tesseract and clipboard utilities hints at calls made via subprocess or Python bindings, which should be visible in the control flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global components
    AppInit["Entry Point"]:::core
    GUI["GUI Layer"]:::core
    ScrnCap["Screen Capture"]:::core
    Clipboard["Clipboard Manager"]:::core
    ExternalTools["Platform Utilities"]:::external

    %% High Level Flow
    AppInit -->|"init_app"| GUI
    GUI -->|"capture_trigger"| ScrnCap

    %% OCR Pipeline subgraph with detailed steps
    subgraph "OCR Pipeline"
        direction TB
        OCR1["Enhance Image"]:::ocr
        OCR2["Recognition"]:::ocr
        OCR3["Tesseract OCR"]:::ocr
        OCR4["Transformers"]:::ocr
        OCR1 -->|"enhance"| OCR2
        OCR2 -->|"recognize"| OCR3
        OCR3 -->|"transform"| OCR4
    end

    %% Continue control flow
    ScrnCap -->|"captured_image"| OCR1
    OCR4 -->|"copy_text"| Clipboard
    Clipboard -->|"notify"| GUI

    %% External interactions
    OCR3 -->|"callTesseract"| ExternalTools
    Clipboard -->|"clipboard_cmd"| ExternalTools

    %% Click Events for component mapping
    click AppInit "https://github.com/dynobo/normcap/blob/main/normcap/__main__.py"
    click GUI "https://github.com/dynobo/normcap/tree/main/normcap/gui"
    click ScrnCap "https://github.com/dynobo/normcap/tree/main/normcap/screengrab"
    click OCR1 "https://github.com/dynobo/normcap/blob/main/normcap/ocr/enhance.py"
    click OCR2 "https://github.com/dynobo/normcap/blob/main/normcap/ocr/recognize.py"
    click OCR3 "https://github.com/dynobo/normcap/blob/main/normcap/ocr/tesseract.py"
    click OCR4 "https://github.com/dynobo/normcap/tree/main/normcap/ocr/transformers"
    click Clipboard "https://github.com/dynobo/normcap/tree/main/normcap/clipboard"
    click ExternalTools "https://github.com/dynobo/normcap/tree/main/bundle/platforms"

    %% Styles
    classDef core fill:#E0E0E0,stroke:#333,stroke-width:1px;
    classDef ocr fill:#D3EBCD,stroke:#2E8B57,stroke-width:2px;
    classDef external fill:#FFEEAA,stroke:#F08A00,stroke-width:2px;
```
