# 0001 - Technology And Packaging Decision

Date: 2026-06-19

Status: accepted for initial implementation planning

## Decision

Use C++20, Windows SDK audio APIs, Steinberg ASIO SDK, MSVC, and CMake for the
initial product implementation.

Use a dependency-free native Win32 skeleton first. Evaluate Dear ImGui with the
Win32/DX11 backend as the leading candidate for the full diagnostic UI before
building the dense parameter/logging interface.

The intended packaging target is a single Windows desktop `.exe` produced from
native code. It may rely on normal Windows system DLLs and user-installed ASIO
drivers, but should not require a separate application runtime, installer, or
global package installation for basic execution.

## Rationale

The product must exercise low-level Windows audio APIs directly:

- MME through `winmm`.
- DirectSound through Windows/DirectX compatibility APIs.
- WASAPI through COM interfaces.
- ASIO through the Steinberg C/C++ SDK and vendor ASIO drivers.

C++ keeps those APIs close to their native form, reduces interop ambiguity, and
fits one-file executable packaging better than a managed runtime stack.

The first Win32 UI is intentionally conservative and keeps the skeleton
dependency-free. For the full diagnostic surface, Dear ImGui may be a better fit
because the application needs dense controls, collapsible advanced sections,
tables, realtime stats, and log panes. That dependency should be added only
after an explicit queued evaluation task.

CMake is selected for project generation and test orchestration because it works
well with MSVC and can keep build commands explicit without committing Visual
Studio-generated user state.

## Rejected Or Deferred Options

### C# / .NET

Pros:

- Faster GUI development.
- Good Windows desktop ergonomics.

Reasons deferred:

- DirectSound and ASIO paths would require P/Invoke, COM wrappers, or third-party
  packages.
- Self-contained single-file .NET output is larger and less direct for driver
  callback diagnostics.
- Audio callback timing and native DSD packing are easier to reason about in
  native code.

### Rust

Pros:

- Strong safety model.
- Good command-line and test tooling.

Reasons deferred:

- Low-level Windows audio and ASIO integration would still involve substantial
  unsafe FFI.
- ASIO SDK integration is C++-oriented.
- The project should first minimize toolchain and binding risk.

### Qt, wxWidgets, Electron, WebView UI

Reasons deferred:

- They add runtime, packaging, or dependency complexity before audio backends are
  proven.
- The application needs dense expert controls, not a marketing-style interface.

## Build And Test Strategy

- Use CMake presets or documented CMake commands after the skeleton is created.
- Use MSVC and Windows SDK locally.
- Use CTest for repeatable test execution.
- Start with dependency-free C++ unit/smoke test executables.
- Keep audio hardware tests as explicit manual smoke checklists until device
  simulators or fixtures exist.
- Do not add package managers or external test frameworks in the first skeleton
  task.

## Packaging Strategy

- Debug builds may produce normal build-tree executables.
- Release packaging should target one primary `.exe`.
- Use static runtime linking only if it does not create licensing, security, or
  maintenance problems; otherwise document the required Visual C++ runtime.
- Do not bundle ASIO drivers.
- Do not bundle or modify system audio drivers.

## Device Stability Implications

This decision must be implemented with `docs/DEVICE_STABILITY_POLICY.md` in
mind. Native C++ should make it possible to control device lifecycle precisely:
initialize once, log every transition, drain before stop, and optionally keep a
valid silent stream alive to avoid unstable USB/ASIO device behavior.

## References

- `docs/DEVICE_STABILITY_POLICY.md`
- `docs/PLAYBACK_TROUBLESHOOTING_PARAMETERS.md`
- `ASIO-SDK_2.3.4_2025-10-15/ASIOSDK/README.md`
- `docs/GPT55_PRO_ALIGNMENT.md`
