# Development Notes

## Local Commands

Recommended:

```bash
uv sync --frozen
uv run scanslicer
```

Alternative:

```bash
python -m scanslicer
```

## Packaging and Entry Points

- Python package metadata: `pyproject.toml`
- Console script: `scanslicer = scanslicer.entry:main`
- Module entry: `python -m scanslicer`

## High-Level Code Layout

- `scanslicer/entry.py`: startup arguments + backend selection
- `scanslicer/main.py`: main window and application bootstrap
- `scanslicer/controller*.py`: user action logic
- `scanslicer/ui_builders*.py`: widget construction
- `scanslicer/canvas*.py`: preview rendering and interactive editing
- `scanslicer/autoslicer*.py`: detection, auto-tune, and feedback engine
- `scanslicer/params.py`: parameter schema and persistence
- `scanslicer/slices.py`: box geometry utilities

## Concurrency Model

- Background work is executed via `QThreadPool`.
- Thread pool is configured to a single worker thread to avoid overlapping detection/autotune tasks.
- UI updates are dispatched through Qt signals.

## Persistence Model Summary

- Defaults and presets are JSON files.
- Auto-tune feedback is a JSON list of historical entries.
- Status log is plain text with session reset per app launch.

All paths are configurable by environment variables (see `docs/runtime-config.md`).

## Current Testing State

- No automated test suite is currently present in this repository.
- Recommended validation after changes:
  - startup on Wayland and X11
  - detection and save flow on representative sample scans
  - auto-tune profile run and feedback write/read cycle
  - AppImage and Docker startup sanity checks