# srikanth-mohankumar/neoview architecture

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

- Interactive diagram: https://gitdiagram.com/srikanth-mohankumar/neoview
- Repository: https://github.com/srikanth-mohankumar/neoview

## Overview

#### Purpose and Entry Points
NeoView is a native Linux/Windows desktop PDF review application: viewing, navigation, search, measurement, crop-to-PNG export, annotation, bookmarks, and reload-aware sessions. The Qt application starts through `src/neoview/__main__.py` and `src/neoview/app.py`; `pdf_crop_measure.py` preserves a legacy launch path. Packaging exposes an installed `neoview` command via `pyproject.toml`.

#### Desktop Runtime and PDF Boundary
The runtime is Python 3.10+ with PySide6 for the event-driven desktop UI and PyMuPDF for PDF reading, text/font inspection, rendering, export, and annotation-related operations. The application boundary is local files and native desktop services (filesystem, clipboard, dialogs); no server or cloud service is implied. Core resource and visual setup reside in `src/neoview/resources.py` and `src/neoview/theme.py`.

#### Application Shell and Document Tabs
`src/neoview/ui/main_window.py` is the composition root and primary controller for multi-document tabs, menus/toolbars, docked panels, keyboard commands, document lifecycle, session restoration, and file-change reload coordination. It owns high-level transitions such as opening/reusing a tab, switching active documents, and preserving per-document state. `src/neoview/app.py` creates the Qt process/window and supplies startup file arguments.

#### PDF View, Rendering, and Interaction
`src/neoview/ui/pdf_view.py` is the main canvas boundary between PDF-backed document data and interactive Qt graphics. It drives page rendering, zoom/fit/rotation, page navigation, text/search overlays, thumbnails or visible-page behavior, and native annotation display. Page-level graphics are represented by `src/neoview/ui/page_item.py`; user rectangular selection, manipulation handles, and measurement geometry are encapsulated in `src/neoview/ui/selection.py`.

#### State and Persistence
Typed in-memory per-view/per-tab state is centralized in `src/neoview/models/view_state.py`, covering document session concerns such as page/zoom and feature state described by the UI. Durable user-created annotations and bookmarks are separated from source PDFs in sidecar files through `src/neoview/persistence/sidecar_store.py`. This boundary lets reloads and source-PDF changes retain NeoView state, while annotated-PDF export remains an explicit output workflow rather than destructive source modification.

#### Review Workflows
Selection feeds several downstream actions: unit conversion and display through `src/neoview/utils/units.py`, crop/export, measurement copying, and creating annotations. Annotation creation, editing, list/filtering, and tool controls are split between `src/neoview/ui/annotation_item.py` and `src/neoview/ui/annotation_toolbar.py`. Dialog-driven workflows—open/save, export choices, properties, and document-related panels—are concentrated in `src/neoview/ui/dialogs.py`.

#### Distribution and Deployment
Native installation is the primary deployment model (`pyproject.toml`, `setup.py`), supplemented by platform launch scripts. Windows standalone builds use PyInstaller configuration in `neoview.spec`; `Dockerfile` supports reproducible or development-oriented container use rather than the core user path. CI is defined in `.github/workflows/ci.yml`, with a separate Windows build pipeline in `.github/workflows/windows-build.yml`.

Main entry points: [`src/neoview/ui/main_window.py`](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/main_window.py) (Main window), [`src/neoview/ui/pdf_view.py`](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/pdf_view.py) (PDF view), [`src/neoview/ui/annotation_item.py`](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/annotation_item.py) (Annotation UI), [`src/neoview/app.py`](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/app.py) (Qt application bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Desktop Runtime"]
  node_entry["Module entry point<br/>CLI entry<br/>[__main__.py]"]
  node_app["Qt application bootstrap<br/>application runtime<br/>[app.py]"]
  node_qt{{"PySide6 desktop services<br/>native UI runtime"}}
  node_pymupdf{{"PyMuPDF<br/>PDF engine"}}
end

subgraph group_ui["UI Shell &amp; Canvas"]
  node_main_window["Main window<br/>composition root<br/>[main_window.py]"]
  node_pdf_view["PDF view<br/>interactive canvas<br/>[pdf_view.py]"]
  node_page_item["Page graphics<br/>graphics item<br/>[page_item.py]"]
  node_selection["Selection &amp; measurement<br/>interaction geometry<br/>[selection.py]"]
  node_annotations["Annotation UI<br/>review controls<br/>[annotation_item.py]"]
  node_annotation_toolbar["Annotation toolbar<br/>review controls"]
  node_dialogs["Document dialogs<br/>dialog workflows<br/>[dialogs.py]"]
  node_resources["Resources<br/>visual assets<br/>[resources.py]"]
  node_theme["Theme<br/>visual styling<br/>[theme.py]"]
end

subgraph group_state["State &amp; Workflows"]
  node_view_state["View state<br/>typed in-memory state<br/>[view_state.py]"]
  node_sidecar[("Sidecar store<br/>durable review state<br/>[sidecar_store.py]")]
  node_units["Unit conversion<br/>measurement utility<br/>[units.py]"]
end

subgraph group_delivery["Distribution"]
  node_package["Package definition<br/>native installation<br/>[pyproject.toml]"]
  node_windows_build["Windows standalone build<br/>PyInstaller build<br/>[neoview.spec]"]
  node_ci["CI<br/>automation pipeline<br/>[ci.yml]"]
end

node_entry -->|"starts"| node_app
node_package -->|"installs command for"| node_entry
node_app -->|"initializes"| node_qt
node_app -->|"creates"| node_main_window
node_main_window -->|"hosts per document tab"| node_pdf_view
node_main_window -->|"preserves tab state"| node_view_state
node_main_window -->|"loads and saves review state"| node_sidecar
node_main_window -->|"launches"| node_dialogs
node_main_window -->|"uses"| node_resources
node_main_window -->|"applies"| node_theme
node_pdf_view -->|"reads and renders PDFs"| node_pymupdf
node_pdf_view -->|"creates page graphics"| node_page_item
node_pdf_view -->|"captures selections"| node_selection
node_pdf_view -->|"displays annotations"| node_annotations
node_selection -->|"converts measurements"| node_units
node_selection -->|"creates annotations from"| node_annotations
node_annotation_toolbar -->|"controls"| node_annotations
node_annotations -->|"persists review data"| node_sidecar
node_windows_build -->|"packages application"| node_package
node_ci -->|"validates"| node_package

click node_entry "https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/__main__.py"
click node_app "https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/app.py"
click node_main_window "https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/main_window.py"
click node_pdf_view "https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/pdf_view.py"
click node_page_item "https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/page_item.py"
click node_selection "https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/selection.py"
click node_annotations "https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/annotation_item.py"
click node_annotation_toolbar "https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/annotation_toolbar.py"
click node_dialogs "https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/dialogs.py"
click node_view_state "https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/models/view_state.py"
click node_sidecar "https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/persistence/sidecar_store.py"
click node_units "https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/utils/units.py"
click node_resources "https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/resources.py"
click node_theme "https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/theme.py"
click node_package "https://github.com/srikanth-mohankumar/neoview/blob/main/pyproject.toml"
click node_windows_build "https://github.com/srikanth-mohankumar/neoview/blob/main/neoview.spec"
click node_ci "https://github.com/srikanth-mohankumar/neoview/blob/main/.github/workflows/ci.yml"

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_entry,node_app,node_qt,node_pymupdf toneBlue
class node_main_window,node_pdf_view,node_page_item,node_selection,node_annotations,node_annotation_toolbar,node_dialogs,node_resources,node_theme toneAmber
class node_view_state,node_sidecar,node_units toneMint
class node_package,node_windows_build,node_ci toneRose
```

## Components

### Desktop Runtime

- [Module entry point](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/__main__.py): CLI entry · `src/neoview/__main__.py`
- [Qt application bootstrap](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/app.py): application runtime · Creates the Qt process, main window, and startup file handling. · `src/neoview/app.py`
- **PySide6 desktop services**: native UI runtime · Event loop, widgets, graphics, dialogs, clipboard, and filesystem integration.
- **PyMuPDF**: PDF engine · Reads, inspects, renders, exports, and annotates PDFs.

### UI Shell & Canvas

- [Main window](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/main_window.py): composition root · Coordinates tabs, commands, document lifecycle, reloads, and sessions. · `src/neoview/ui/main_window.py`
- [PDF view](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/pdf_view.py): interactive canvas · Connects PDF data to rendering, navigation, zoom, search, and overlays. · `src/neoview/ui/pdf_view.py`
- [Page graphics](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/page_item.py): graphics item · `src/neoview/ui/page_item.py`
- [Selection & measurement](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/selection.py): interaction geometry · Owns rectangular selection, handles, and measurement geometry. · `src/neoview/ui/selection.py`
- [Annotation UI](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/annotation_item.py): review controls · Provides annotation items, editing, filtering, and tool controls. · `src/neoview/ui/annotation_item.py`
- [Annotation toolbar](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/annotation_toolbar.py): review controls · `src/neoview/ui/annotation_toolbar.py`
- [Document dialogs](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/ui/dialogs.py): dialog workflows · Handles open/save, export, properties, and document panels. · `src/neoview/ui/dialogs.py`
- [Resources](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/resources.py): visual assets · `src/neoview/resources.py`
- [Theme](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/theme.py): visual styling · `src/neoview/theme.py`

### State & Workflows

- [View state](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/models/view_state.py): typed in-memory state · Stores per-tab session, page, zoom, and feature state. · `src/neoview/models/view_state.py`
- [Sidecar store](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/persistence/sidecar_store.py): durable review state · Persists annotations and bookmarks separately from source PDFs. · `src/neoview/persistence/sidecar_store.py`
- [Unit conversion](https://github.com/srikanth-mohankumar/neoview/blob/main/src/neoview/utils/units.py): measurement utility · `src/neoview/utils/units.py`

### Distribution

- [Package definition](https://github.com/srikanth-mohankumar/neoview/blob/main/pyproject.toml): native installation · Exposes the installed neoview command. · `pyproject.toml`
- [Windows standalone build](https://github.com/srikanth-mohankumar/neoview/blob/main/neoview.spec): PyInstaller build · `neoview.spec`
- [CI](https://github.com/srikanth-mohankumar/neoview/blob/main/.github/workflows/ci.yml): automation pipeline · `.github/workflows/ci.yml`

## Connections

- Module entry point → Qt application bootstrap: starts
- Package definition → Module entry point: installs command for
- Qt application bootstrap → PySide6 desktop services: initializes
- Qt application bootstrap → Main window: creates
- Main window → PDF view: hosts per document tab
- Main window → View state: preserves tab state
- Main window → Sidecar store: loads and saves review state
- Main window → Document dialogs: launches
- Main window → Resources: uses
- Main window → Theme: applies
- PDF view → PyMuPDF: reads and renders PDFs
- PDF view → Page graphics: creates page graphics
- PDF view → Selection & measurement: captures selections
- PDF view → Annotation UI: displays annotations
- Selection & measurement → Unit conversion: converts measurements
- Selection & measurement → Annotation UI: creates annotations from
- Annotation toolbar → Annotation UI: controls
- Annotation UI → Sidecar store: persists review data
- Windows standalone build → Package definition: packages application
- CI → Package definition: validates