# qpg-mit/optiverse architecture

> Architecture diagram of the GitHub repository qpg-mit/optiverse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qpg-mit/optiverse
- Repository: https://github.com/qpg-mit/optiverse

## Overview

Optiverse is a PyQt6 desktop tool for building 2D optical assemblies, editing components, and interactively tracing and viewing rays. Users place and configure optical elements and sources on a canvas; the ray-tracing controller invokes the engine and rendering displays propagation. File workflows save and reload assemblies, while separate features support component libraries, Zemax import, linked assemblies, measurements, and live collaboration. Edges are limited to relationships explicit in the README or source index; many UI and domain integrations are not excerpted, so omitted links should not be read as absent.

Main entry points: [`src/optiverse/ui/views/main_window.py`](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/views/main_window.py) (Application window), [`src/optiverse/services/scene_file_manager.py`](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/scene_file_manager.py) (Assembly save and load), [`src/optiverse/services/collaboration_manager.py`](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/collaboration_manager.py) (Collaboration manager), [`src/optiverse/core/undo_stack.py`](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/core/undo_stack.py) (Undo stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop interaction"]
  node_main["Application window<br/>[main_window.py]"]
  node_canvas["Scene interaction"]
  node_placement["Component placement"]
  node_drag["Move and rotate"]
  node_measure["Measurement tools<br/>[tool_handlers.py]"]
  node_graphics["Canvas views<br/>[graphics_view.py]"]
  node_theme["Theme management<br/>[theme_manager.py]"]
end

subgraph group_optics["Optical modeling"]
  node_objects["Optical objects<br/>[base_obj.py]"]
  node_components["Component creation"]
  node_raycontroller["Ray tracing control"]
  node_engine["Ray tracing engine<br/>[engine.py]"]
  node_rays["Ray models<br/>[ray.py]"]
  node_rayrender["Ray rendering<br/>[ray_renderer.py]"]
end

subgraph group_files["Assembly and libraries"]
  node_files["Assembly save and load"]
  node_storage[("Persistent storage<br/>[storage_service.py]")]
  node_library["Component library<br/>[library_service.py]"]
  node_registry["Serializable type registry<br/>[type_registry.py]"]
  node_zemax["Zemax import<br/>[zemax_parser.py]"]
  node_linked["Linked assemblies"]
end

subgraph group_services["Collaboration and services"]
  node_collab_controller["Collaboration controls"]
  node_collab["Collaboration manager"]
  node_network["Collaboration service"]
  node_logging["Logging service<br/>[log_service.py]"]
  node_errors["Error handling<br/>[error_handler.py]"]
end

subgraph group_core["Shared application state"]
  node_layers["Layer tree state"]
  node_undo["Undo commands<br/>[undo_commands.py]"]
  node_undo_stack["Undo stack<br/>[undo_stack.py]"]
  node_models["Optical models<br/>[models.py]"]
  node_preferences["Preferences<br/>[preferences.py]"]
  node_paths["Platform paths<br/>[paths.py]"]
end

node_user(("Optics designer"))
node_peers(("Collaboration peers"))

node_user -->|"uses"| node_main
node_main -->|"applies"| node_theme
node_main -.->|"handles scene events"| node_canvas
node_canvas -->|"dispatches tools"| node_placement
node_canvas -->|"delegates drags"| node_drag
node_placement -->|"creates items"| node_components
node_placement -->|"records placement"| node_undo_stack
node_drag -->|"records moves"| node_undo_stack
node_drag -->|"reads group state"| node_layers
node_measure -->|"records measurements"| node_undo_stack
node_measure -->|"reads ray paths"| node_rays
node_main -.->|"coordinates tracing"| node_raycontroller
node_raycontroller -->|"traces rays"| node_engine
node_raycontroller -->|"updates display"| node_rayrender
node_engine -->|"produces paths"| node_rays
node_engine -->|"uses optical models"| node_models
node_main -->|"saves assemblies"| node_files
node_files -->|"serializes items"| node_registry
node_files -->|"loads layer state"| node_layers
node_files -->|"resolves linked data"| node_linked
node_files -.->|"persists data"| node_storage
node_registry -.->|"restores item types"| node_components
node_main -->|"manages library"| node_library
node_library -->|"uses storage"| node_storage
node_main -.->|"imports designs"| node_zemax
node_user -->|"references assemblies"| node_linked
node_user -->|"imports Zemax"| node_zemax
node_user -->|"measures optics"| node_measure
node_user -->|"starts collaboration"| node_collab_controller
node_collab_controller -->|"controls session"| node_collab
node_collab -->|"synchronizes state"| node_network
node_collab -->|"updates scene state"| node_layers
node_peers -->|"connects"| node_network
node_preferences -.->|"loads settings"| node_storage
node_files -->|"resolves file paths"| node_paths
node_collab -->|"logs activity"| node_logging
node_errors -->|"reports errors"| node_logging
node_main -->|"installs handling"| node_errors
node_main -.->|"presents canvas"| node_graphics
node_user -->|"configures optics"| node_objects
node_undo_stack -->|"executes commands"| node_undo

click node_main "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/views/main_window.py"
click node_canvas "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/views/scene_event_handler.py"
click node_placement "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/views/placement_handler.py"
click node_drag "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/controllers/item_drag_handler.py"
click node_measure "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/views/tool_handlers.py"
click node_graphics "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/objects/views/graphics_view.py"
click node_objects "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/objects/base_obj.py"
click node_components "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/objects/component_factory.py"
click node_raycontroller "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/controllers/raytracing_controller.py"
click node_engine "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/raytracing/engine.py"
click node_rays "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/raytracing/ray.py"
click node_rayrender "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/controllers/ray_renderer.py"
click node_layers "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/core/layer_tree_state.py"
click node_undo "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/core/undo_commands.py"
click node_undo_stack "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/core/undo_stack.py"
click node_models "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/core/models.py"
click node_files "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/scene_file_manager.py"
click node_storage "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/storage_service.py"
click node_library "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/library_service.py"
click node_registry "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/objects/type_registry.py"
click node_zemax "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/zemax_parser.py"
click node_linked "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/linked_assembly_service.py"
click node_collab_controller "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/controllers/collaboration_controller.py"
click node_collab "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/collaboration_manager.py"
click node_network "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/collaboration_service.py"
click node_logging "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/log_service.py"
click node_preferences "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/core/preferences.py"
click node_paths "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/platform/paths.py"
click node_theme "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/theme_manager.py"
click node_errors "https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/error_handler.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_main,node_canvas,node_placement,node_drag,node_measure,node_graphics,node_theme toneBlue
class node_objects,node_components,node_raycontroller,node_engine,node_rays,node_rayrender toneAmber
class node_files,node_storage,node_library,node_registry,node_zemax,node_linked toneMint
class node_collab_controller,node_collab,node_network,node_logging,node_errors toneRose
class node_layers,node_undo,node_undo_stack,node_models,node_preferences,node_paths,node_user,node_peers toneIndigo
```

## Components

### Desktop interaction

- [Application window](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/views/main_window.py): `src/optiverse/ui/views/main_window.py`
- [Scene interaction](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/views/scene_event_handler.py): `src/optiverse/ui/views/scene_event_handler.py`
- [Component placement](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/views/placement_handler.py): `src/optiverse/ui/views/placement_handler.py`
- [Move and rotate](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/controllers/item_drag_handler.py): `src/optiverse/ui/controllers/item_drag_handler.py`
- [Measurement tools](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/views/tool_handlers.py): `src/optiverse/ui/views/tool_handlers.py`
- [Canvas views](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/objects/views/graphics_view.py): `src/optiverse/objects/views/graphics_view.py`
- [Theme management](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/theme_manager.py): `src/optiverse/ui/theme_manager.py`

### Optical modeling

- [Optical objects](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/objects/base_obj.py): `src/optiverse/objects/base_obj.py`
- [Component creation](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/objects/component_factory.py): `src/optiverse/objects/component_factory.py`
- [Ray tracing control](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/controllers/raytracing_controller.py): `src/optiverse/ui/controllers/raytracing_controller.py`
- [Ray tracing engine](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/raytracing/engine.py): `src/optiverse/raytracing/engine.py`
- [Ray models](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/raytracing/ray.py): `src/optiverse/raytracing/ray.py`
- [Ray rendering](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/controllers/ray_renderer.py): `src/optiverse/ui/controllers/ray_renderer.py`

### Assembly and libraries

- [Assembly save and load](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/scene_file_manager.py): `src/optiverse/services/scene_file_manager.py`
- [Persistent storage](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/storage_service.py): `src/optiverse/services/storage_service.py`
- [Component library](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/library_service.py): `src/optiverse/services/library_service.py`
- [Serializable type registry](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/objects/type_registry.py): `src/optiverse/objects/type_registry.py`
- [Zemax import](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/zemax_parser.py): `src/optiverse/services/zemax_parser.py`
- [Linked assemblies](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/linked_assembly_service.py): `src/optiverse/services/linked_assembly_service.py`

### Collaboration and services

- [Collaboration controls](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/ui/controllers/collaboration_controller.py): `src/optiverse/ui/controllers/collaboration_controller.py`
- [Collaboration manager](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/collaboration_manager.py): `src/optiverse/services/collaboration_manager.py`
- [Collaboration service](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/collaboration_service.py): `src/optiverse/services/collaboration_service.py`
- [Logging service](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/log_service.py): `src/optiverse/services/log_service.py`
- [Error handling](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/services/error_handler.py): `src/optiverse/services/error_handler.py`

### Shared application state

- [Layer tree state](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/core/layer_tree_state.py): `src/optiverse/core/layer_tree_state.py`
- [Undo commands](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/core/undo_commands.py): `src/optiverse/core/undo_commands.py`
- [Undo stack](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/core/undo_stack.py): `src/optiverse/core/undo_stack.py`
- [Optical models](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/core/models.py): `src/optiverse/core/models.py`
- [Preferences](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/core/preferences.py): `src/optiverse/core/preferences.py`
- [Platform paths](https://github.com/qpg-mit/optiverse/blob/main/src/optiverse/platform/paths.py): `src/optiverse/platform/paths.py`

### Other components

- **Optics designer**
- **Collaboration peers**

## Connections

- Optics designer → Application window: uses (evidence: `README.md`)
- Application window → Theme management: applies (evidence: `src/optiverse/app/main.py`)
- Application window → Scene interaction: handles scene events
- Scene interaction → Component placement: dispatches tools (evidence: `src/optiverse/ui/views/scene_event_handler.py`)
- Scene interaction → Move and rotate: delegates drags (evidence: `src/optiverse/ui/views/scene_event_handler.py`)
- Component placement → Component creation: creates items (evidence: `src/optiverse/ui/views/placement_handler.py`)
- Component placement → Undo stack: records placement (evidence: `src/optiverse/ui/views/placement_handler.py`)
- Move and rotate → Undo stack: records moves (evidence: `src/optiverse/ui/controllers/item_drag_handler.py`)
- Move and rotate → Layer tree state: reads group state (evidence: `src/optiverse/ui/controllers/item_drag_handler.py`)
- Measurement tools → Undo stack: records measurements (evidence: `src/optiverse/ui/views/tool_handlers.py`)
- Measurement tools → Ray models: reads ray paths (evidence: `src/optiverse/ui/views/tool_handlers.py`)
- Application window → Ray tracing control: coordinates tracing
- Ray tracing control → Ray tracing engine: traces rays (evidence: `src/optiverse/ui/controllers/raytracing_controller.py`)
- Ray tracing control → Ray rendering: updates display (evidence: `src/optiverse/ui/controllers/raytracing_controller.py`)
- Ray tracing engine → Ray models: produces paths (evidence: `src/optiverse/raytracing/engine.py`)
- Ray tracing engine → Optical models: uses optical models (evidence: `src/optiverse/raytracing/engine.py`)
- Application window → Assembly save and load: saves assemblies
- Assembly save and load → Serializable type registry: serializes items (evidence: `src/optiverse/services/scene_file_manager.py`)
- Assembly save and load → Layer tree state: loads layer state (evidence: `src/optiverse/services/scene_file_manager.py`)
- Assembly save and load → Linked assemblies: resolves linked data (evidence: `src/optiverse/services/scene_file_manager.py`)
- Assembly save and load → Persistent storage: persists data
- Serializable type registry → Component creation: restores item types
- Application window → Component library: manages library
- Component library → Persistent storage: uses storage (evidence: `src/optiverse/ui/controllers/library_manager.py`)
- Application window → Zemax import: imports designs
- Optics designer → Linked assemblies: references assemblies (evidence: `README.md`)
- Optics designer → Zemax import: imports Zemax (evidence: `README.md`)
- Optics designer → Measurement tools: measures optics (evidence: `README.md`)
- Optics designer → Collaboration controls: starts collaboration (evidence: `README.md`)
- Collaboration controls → Collaboration manager: controls session (evidence: `src/optiverse/ui/controllers/collaboration_controller.py`)
- Collaboration manager → Collaboration service: synchronizes state (evidence: `src/optiverse/services/collaboration_manager.py`)
- Collaboration manager → Layer tree state: updates scene state (evidence: `src/optiverse/services/collaboration_manager.py`)
- Collaboration peers → Collaboration service: connects (evidence: `README.md`)
- Preferences → Persistent storage: loads settings
- Assembly save and load → Platform paths: resolves file paths (evidence: `src/optiverse/services/scene_file_manager.py`)
- Collaboration manager → Logging service: logs activity (evidence: `src/optiverse/services/collaboration_manager.py`)
- Error handling → Logging service: reports errors (evidence: `src/optiverse/services/error_handler.py`)
- Application window → Error handling: installs handling (evidence: `src/optiverse/app/main.py`)
- Application window → Canvas views: presents canvas
- Optics designer → Optical objects: configures optics (evidence: `README.md`)
- Undo stack → Undo commands: executes commands (evidence: `src/optiverse/core/undo_stack.py`)
