# remesis/rivenlens architecture

> Architecture diagram of the GitHub repository remesis/rivenlens, 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/remesis/rivenlens
- Repository: https://github.com/remesis/rivenlens
- Video tour (about a minute): https://gitdiagram.com/remesis/rivenlens/video

## Overview

RivenLens is a local Windows desktop companion that reads visible Riven cards without accessing game or account data. The main workflow is user-started monitor capture, local OCR and card interpretation, roll tracking, then display of current and proposed grades. The planner adds splice, lock and odds stages; settings, alerts and optional GitHub updates are supporting branches. The worker and window excerpts establish the capture/display coordination; some subsystem links reflect README-documented capabilities where implementation excerpts were unavailable.

Main entry points: [`native/window.py`](https://github.com/remesis/rivenlens/blob/main/native/window.py) (Main window), [`native/worker.py`](https://github.com/remesis/rivenlens/blob/main/native/worker.py) (Capture worker), [`app/reader.py`](https://github.com/remesis/rivenlens/blob/main/app/reader.py) (Frame reader), [`native/planner.py`](https://github.com/remesis/rivenlens/blob/main/native/planner.py) (Planner logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_window["Main window<br/>[window.py]"]
  node_widgets["Roll cards<br/>[widgets.py]"]
end

subgraph group_reading["Screen reading"]
  node_worker["Capture worker<br/>[worker.py]"]
  node_capture["Monitor capture<br/>[capture.py]"]
  node_reader["Frame reader<br/>[reader.py]"]
  node_ocr["Local OCR<br/>[ocr_engine.py]"]
  node_parser["Card parser<br/>[parser.py]"]
  node_tracker["Roll tracker<br/>[tracker.py]"]
  node_warning["Read warning<br/>[stat_warning.py]"]
end

subgraph group_grading["Grades and planning"]
  node_catalog["Riven catalog<br/>[catalog.py]"]
  node_grading["Roll grading<br/>[grading.py]"]
  node_planner["Target planner<br/>[planner_view.py]"]
  node_planner_logic["Planner logic<br/>[planner.py]"]
  node_odds["Final odds<br/>[odds.py]"]
end

subgraph group_settings["Preferences and alerts"]
  node_preferences[("Saved preferences<br/>[preferences.py]")]
  node_settings_view["Settings dialog<br/>[settings_view.py]"]
  node_audio["Audio presets<br/>[audio.py]"]
  node_alerts["Grade alerts<br/>[alerts.py]"]
end

subgraph group_updates["Optional updates"]
  node_release_config["Release config<br/>[releases.py]"]
  node_updates["Startup updates<br/>[updates.py]"]
  node_update_network["Update network<br/>[update_network.py]"]
  node_update_session["Install session<br/>[update_session.py]"]
end

node_user(("Player"))
node_github(("GitHub releases"))

node_user -->|"controls"| node_window
node_window -->|"configures"| node_worker
node_worker -->|"grabs pixels"| node_capture
node_worker -->|"reads frames"| node_reader
node_reader -->|"recognizes text"| node_ocr
node_reader -->|"parses lines"| node_parser
node_worker -->|"tracks rolls"| node_tracker
node_tracker -->|"checks stats"| node_warning
node_worker -->|"publishes readings"| node_window
node_window -->|"renders grades"| node_widgets
node_window -->|"requests grades"| node_grading
node_grading -->|"reads references"| node_catalog
node_window -->|"opens planner"| node_planner
node_planner -->|"updates targets"| node_planner_logic
node_planner_logic -->|"reads catalog"| node_catalog
node_planner_logic -->|"calculates odds"| node_odds
node_window -->|"opens settings"| node_settings_view
node_window -->|"loads and saves"| node_preferences
node_settings_view -->|"saves choices"| node_preferences
node_window -->|"checks matches"| node_alerts
node_alerts -->|"plays sounds"| node_audio
node_window -->|"loads release"| node_release_config
node_window -.->|"schedules check"| node_updates
node_updates -.->|"checks release"| node_update_network
node_update_network -.->|"requests releases"| node_github
node_updates -.->|"starts install"| node_update_session

click node_window "https://github.com/remesis/rivenlens/blob/main/native/window.py"
click node_widgets "https://github.com/remesis/rivenlens/blob/main/native/widgets.py"
click node_worker "https://github.com/remesis/rivenlens/blob/main/native/worker.py"
click node_capture "https://github.com/remesis/rivenlens/blob/main/app/capture.py"
click node_reader "https://github.com/remesis/rivenlens/blob/main/app/reader.py"
click node_ocr "https://github.com/remesis/rivenlens/blob/main/app/ocr_engine.py"
click node_parser "https://github.com/remesis/rivenlens/blob/main/app/parser.py"
click node_tracker "https://github.com/remesis/rivenlens/blob/main/app/tracker.py"
click node_warning "https://github.com/remesis/rivenlens/blob/main/app/stat_warning.py"
click node_catalog "https://github.com/remesis/rivenlens/blob/main/native/catalog.py"
click node_grading "https://github.com/remesis/rivenlens/blob/main/native/grading.py"
click node_planner "https://github.com/remesis/rivenlens/blob/main/native/planner_view.py"
click node_planner_logic "https://github.com/remesis/rivenlens/blob/main/native/planner.py"
click node_odds "https://github.com/remesis/rivenlens/blob/main/native/odds.py"
click node_preferences "https://github.com/remesis/rivenlens/blob/main/native/preferences.py"
click node_settings_view "https://github.com/remesis/rivenlens/blob/main/native/settings_view.py"
click node_audio "https://github.com/remesis/rivenlens/blob/main/native/audio.py"
click node_alerts "https://github.com/remesis/rivenlens/blob/main/native/alerts.py"
click node_release_config "https://github.com/remesis/rivenlens/blob/main/native/releases.py"
click node_updates "https://github.com/remesis/rivenlens/blob/main/native/updates.py"
click node_update_network "https://github.com/remesis/rivenlens/blob/main/native/update_network.py"
click node_update_session "https://github.com/remesis/rivenlens/blob/main/native/update_session.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_window,node_widgets toneBlue
class node_worker,node_capture,node_reader,node_ocr,node_parser,node_tracker,node_warning toneAmber
class node_catalog,node_grading,node_planner,node_planner_logic,node_odds toneMint
class node_preferences,node_settings_view,node_audio,node_alerts toneRose
class node_release_config,node_updates,node_update_network,node_update_session,node_user,node_github toneIndigo
```

## Components

### Desktop experience

- [Main window](https://github.com/remesis/rivenlens/blob/main/native/window.py): `native/window.py`
- [Roll cards](https://github.com/remesis/rivenlens/blob/main/native/widgets.py): `native/widgets.py`

### Screen reading

- [Capture worker](https://github.com/remesis/rivenlens/blob/main/native/worker.py): `native/worker.py`
- [Monitor capture](https://github.com/remesis/rivenlens/blob/main/app/capture.py): `app/capture.py`
- [Frame reader](https://github.com/remesis/rivenlens/blob/main/app/reader.py): `app/reader.py`
- [Local OCR](https://github.com/remesis/rivenlens/blob/main/app/ocr_engine.py): `app/ocr_engine.py`
- [Card parser](https://github.com/remesis/rivenlens/blob/main/app/parser.py): `app/parser.py`
- [Roll tracker](https://github.com/remesis/rivenlens/blob/main/app/tracker.py): `app/tracker.py`
- [Read warning](https://github.com/remesis/rivenlens/blob/main/app/stat_warning.py): `app/stat_warning.py`

### Grades and planning

- [Riven catalog](https://github.com/remesis/rivenlens/blob/main/native/catalog.py): `native/catalog.py`
- [Roll grading](https://github.com/remesis/rivenlens/blob/main/native/grading.py): `native/grading.py`
- [Target planner](https://github.com/remesis/rivenlens/blob/main/native/planner_view.py): `native/planner_view.py`
- [Planner logic](https://github.com/remesis/rivenlens/blob/main/native/planner.py): `native/planner.py`
- [Final odds](https://github.com/remesis/rivenlens/blob/main/native/odds.py): `native/odds.py`

### Preferences and alerts

- [Saved preferences](https://github.com/remesis/rivenlens/blob/main/native/preferences.py): `native/preferences.py`
- [Settings dialog](https://github.com/remesis/rivenlens/blob/main/native/settings_view.py): `native/settings_view.py`
- [Audio presets](https://github.com/remesis/rivenlens/blob/main/native/audio.py): `native/audio.py`
- [Grade alerts](https://github.com/remesis/rivenlens/blob/main/native/alerts.py): `native/alerts.py`

### Optional updates

- [Release config](https://github.com/remesis/rivenlens/blob/main/native/releases.py): `native/releases.py`
- [Startup updates](https://github.com/remesis/rivenlens/blob/main/native/updates.py): `native/updates.py`
- [Update network](https://github.com/remesis/rivenlens/blob/main/native/update_network.py): `native/update_network.py`
- [Install session](https://github.com/remesis/rivenlens/blob/main/native/update_session.py): `native/update_session.py`

### Other components

- **Player**
- **GitHub releases**

## Connections

- Player → Main window: controls
- Main window → Capture worker: configures
- Capture worker → Monitor capture: grabs pixels
- Capture worker → Frame reader: reads frames
- Frame reader → Local OCR: recognizes text
- Frame reader → Card parser: parses lines
- Capture worker → Roll tracker: tracks rolls
- Roll tracker → Read warning: checks stats
- Capture worker → Main window: publishes readings
- Main window → Roll cards: renders grades
- Main window → Roll grading: requests grades
- Roll grading → Riven catalog: reads references
- Main window → Target planner: opens planner
- Target planner → Planner logic: updates targets
- Planner logic → Riven catalog: reads catalog
- Planner logic → Final odds: calculates odds
- Main window → Settings dialog: opens settings
- Main window → Saved preferences: loads and saves
- Settings dialog → Saved preferences: saves choices
- Main window → Grade alerts: checks matches
- Grade alerts → Audio presets: plays sounds
- Main window → Release config: loads release
- Main window → Startup updates: schedules check
- Startup updates → Update network: checks release
- Update network → GitHub releases: requests releases
- Startup updates → Install session: starts install