MyAiConfiguration/shared/rules/wpf/references/architecture-and-quality.md

## Architecture

* Keep presentation, application, domain and infrastructure concerns separated.
* Avoid direct database access from views or ViewModels.
* Avoid direct HTTP access from controls.
* Keep external integrations behind focused services.
* Avoid circular dependencies.
* Keep feature boundaries clear.
* Do not create shared utility classes for unrelated functionality.
* Keep shared code genuinely reusable.
* Minimize global state.
* Avoid static service access.

## Dependency Injection

* Use dependency injection where lifecycle management, substitution or testability benefits from it.
* Avoid service locator patterns.
* Keep constructor dependencies minimal.
* Do not inject dependencies that are not used.
* Choose service lifetimes intentionally.
* Do not make stateful services global without a concrete reason.
* Avoid introducing interfaces solely for dependency injection when no abstraction is needed.

## Testing

* Keep ViewModels testable without a UI thread where practical.
* Test behavior rather than implementation details.
* Test domain and application logic independently from WPF.
* Avoid brittle tests coupled to XAML structure.
* Keep UI automation tests focused on critical flows.
* Mock external boundaries rather than internal details.
* Keep tests deterministic.
* Avoid real network, database or filesystem dependencies in unit tests unless explicitly intended.

## Code Quality

* Use nullable reference types.
* Prefer modern, readable C# syntax.
* Avoid unnecessary interfaces and abstractions.
* Prefer concrete types where no abstraction is required.
* Use descriptive names.
* Remove dead code.
* Remove commented-out code.
* Do not add comments unless the user explicitly requests them.
* Treat compiler, analyzer and binding warnings seriously.
* Do not suppress warnings without a concrete reason.
* Prefer correctness, responsiveness, security and maintainability over cleverness.

## Performance

* Keep the UI thread responsive.
* Minimize visual tree depth.
* Keep virtualization enabled.
* Avoid unnecessary bindings.
* Avoid unnecessary converters.
* Avoid unnecessary resource lookups.
* Avoid unnecessary property change notifications.
* Avoid frequent full collection refreshes.
* Avoid loading large datasets eagerly.
* Avoid loading large images at full resolution when unnecessary.
* Freeze `Freezable` objects where practical.
* Reuse immutable resources where appropriate.
* Avoid unnecessary animations.
* Avoid high-frequency timers on the UI thread.
* Measure startup time, UI responsiveness, memory usage and rendering performance before micro-optimizing.

## Performance Priority

Prioritize WPF performance work in this order:

* UI architecture
* UI thread blocking
* Data loading and I/O
* Virtualization
* Visual tree complexity
* Binding and notification frequency
* Rendering and images
* Memory retention and leaks
* Allocations
* CPU micro-optimizations

Never optimize based purely on assumptions.