panopainter/docs/adr/0001-modernization-boundaries.md

ADR 0001: Incremental Component Boundaries

Status: accepted Date: 2026-05-31

Context

PanoPainter currently has a flat src/ layout with broad dependencies through pch.h, global singletons such as App::I and Canvas::I, OpenGL types in high-level painting/document headers, and duplicated platform source lists. The modernization work must retain existing behavior across Windows desktop and AppX, macOS, iOS, Android standard, Quest, Focus/Wave, Linux, and WebGL.

Decision

Modernization will proceed incrementally. OpenGL remains the production renderer while component boundaries and tests are introduced. Vulkan, Metal, and WebGPU-related work must stay out of the production path until OpenGL parity tests exist.

The target dependency direction is:

pp_foundation
  -> pp_assets
  -> pp_paint
  -> pp_document
  -> pp_renderer_api
  -> pp_renderer_gl
  -> pp_paint_renderer
  -> pp_ui_core
  -> pp_panopainter_ui
  -> pp_platform_*
  -> panopainter_app

Pure component headers must not include platform SDK headers or graphics API headers. Temporary shims are allowed only when recorded in docs/modernization/debt.md.

Consequences

• The first implementation steps are documentation, inventory, CMake skeleton, diagnostics, and tests, not a renderer rewrite.
• Existing project files remain until the shared CMake targets are validated.
• Refactors should prefer additive compatibility layers before moving behavior.
• Every extracted component must gain its own tests before the next component boundary is extracted.