# AxiDraw Integration Architecture

This directory contains the AxiDraw integration used by AxiControl. Most code under
`axidrawinternal/` is ported from the upstream AxiDraw codebase, while the surrounding
modules provide the application-facing API.

This document describes the current structure, the intended public surface, and a
proposed path to consolidate options without rewriting upstream logic.

## Current Layout

Top-level modules

- `axidraw.py`
Public API for the AxiDraw integration. Defines `AxiDraw` class that extends the
upstream implementation and exposes plot/run helpers.

- `README.txt`, `LICENSE.txt`, `copying.txt`
Upstream documentation and licensing.

Upstream port

- `axidrawinternal/`
Ported AxiDraw implementation and helpers. This is treated as vendor code.

Key upstream modules

- `axidrawinternal/axidraw.py`
Core implementation for plotting, control, and device communication.

- `axidrawinternal/motion.py`
Motion planning and movement generation.

- `axidrawinternal/serial_utils.py`
Serial port discovery and connection utilities.

- `axidrawinternal/preview.py`
Preview rendering and velocity chart data.

- `axidrawinternal/digest_svg.py`
Digest computation and SVG handling for optimization modes.

- `axidrawinternal/plot_optimizations.py`
Path ordering and optimization logic.

- `axidrawinternal/axidraw_options/`
Argparse options used by the upstream implementation.

## Intended Public Surface

Only one module should be considered stable for app use:

- `axidraw.py` as the public entry point.

All other modules under `axidrawinternal/` should be treated as internal vendor code
and should not be imported directly by other parts of the application.

## Option Consolidation (Proposed)

Goal: make it easy to see and validate the options used by AxiControl without
modifying the upstream argparse definitions.

Proposed approach

- Add a new local config type, e.g. `axi_control/axidraw/options.py`, that defines
  a dataclass representing the full option set used by the app.

- Provide a single conversion function that maps upstream argparse options into
  the local config object.

- Keep the upstream option definitions unchanged in
  `axidrawinternal/axidraw_options/`, but centralize defaults and validation in the
  new local config type.

Benefits

- One canonical place to understand and validate all options.
- Reduced coupling to upstream argparse internals.
- Easier to document and test the app-facing behavior.

## Next Refactor Steps (Non-Blocking)

- Consider adding `__init__.py` in this directory to make the package boundary explicit
  and re-export the public API only.

- Optionally rename or move `axidrawinternal/` to a clearer vendor namespace
  (e.g. `axidraw_vendor/`) to make the separation obvious.
