Add Ehwrj clean-room live map

docs/architecture.md

@@ -0,0 +1,84 @@
+# Architecture
+
+Ehwrj is split into small modules so that local API access, state derivation, rendering, and platform integration stay separate.
+
+## Data Flow
+
+```text
+War Thunder local API
+  -> Ehwrj.Core.Services.WarThunderClient
+  -> Ehwrj.App.Services.LiveMapService
+  -> Ehwrj.App.Models.LiveSnapshot
+  -> MainWindow / OverlayWindow
+  -> MapCanvas / OverlayCanvas
+```
+
+## Modules
+
+### Ehwrj.Core
+
+- `WarThunderClient` is the only module allowed to perform network requests.
+- Its base address is fixed to `http://127.0.0.1:8111/`.
+- `ProcessProbe` checks whether `aces.exe` is present.
+- `MapInfo` parses `/map_info.json`.
+- `MapObject` parses `/map_obj.json`.
+- `FlightState` parses optional `/state` telemetry such as `TAS, km/h`, `IAS, km/h`, `Vy, m/s`, and `H, m`.
+- `BattleMessage` normalizes optional `/hudmsg` and `/gamechat` messages.
+- `MapObjectKind` classifies player, ally, squad, enemy, objective, and unknown objects.
+- `ObjectTracker` estimates motion from consecutive object positions.
+- `CoordinateProjector` converts map coordinates into viewport coordinates.
+
+`Ehwrj.Core` targets plain `net8.0` and has no UI dependency.
+
+Parser tolerance is intentionally concentrated in `Ehwrj.Core`:
+
+- numeric JSON strings are parsed with invariant culture and comma decimal fallback
+- map bounds can come from scalar min/max fields, `map_min`/`map_max` arrays, `bounds`, or `grid_size`
+- object position can come from scalar `x`/`y` style fields or `pos`/`position` style arrays
+- object direction can come from scalar `dx`/`dy` style fields or `dir`/`direction`/`velocity` style arrays
+
+### Ehwrj.App
+
+- `LiveMapService` owns the polling loop and converts endpoint responses into immutable UI snapshots.
+- `SettingsStore` persists user settings under `%LOCALAPPDATA%\Ehwrj`.
+- `OverlaySettings` holds user-adjustable overlay controls.
+- `UiText` and `LanguageOption` provide the clean-room English/Korean UI language layer.
+- `LiveSnapshot` is the single render input for both the main map and overlay.
+- `MainViewModel` coordinates commands and live state for the Avalonia UI.
+
+### Rendering
+
+- `MapCanvas` draws the main map preview, including player-relative rotation of the map plane and projected tactical objects.
+- `OverlayCanvas` draws the transparent overlay surface.
+- Rendering code receives a `LiveSnapshot` and `OverlaySettings`; it does not perform I/O.
+- Overlay setting changes invalidate the drawing surface directly, so UI sliders and text settings are reflected without restarting the polling loop.
+
+### Overlay Controls
+
+The overlay settings mirror the benign controls identified in the analyzed live map resource:
+
+- minimap visibility, aircraft scale, and Mach threshold
+- spot radar visibility, detection range, spread, vertical scale, and vertical offset
+- marker opacity, arrow scale, arrow outline, and colors
+- distance, Mach, and closure speed label toggles
+- per-label font size, outline width, color, and opacity
+
+### Platform Integration
+
+- `Win32.MakeOverlayClickThrough` is the only Windows interop hook.
+- It applies click-through and no-activate extended styles to the optional overlay window.
+- It is guarded with `OperatingSystem.IsWindows()`.
+
+### Developer Tooling
+
+- `Ehwrj.Tools.LocalApiStub` serves deterministic `/map_info.json`, `/map_obj.json`, and `/map.img` responses on loopback.
+- It also serves optional `/state`, `/hudmsg`, and `/gamechat` responses for player info and battle log development.
+- The stub lets contributors exercise the UI without running War Thunder.
+- The generated map image is produced in memory and the moving aircraft data is deterministic.
+- `Ehwrj.Tools.Capture` captures real local API responses into fixture directories.
+- It writes `capture-report.txt` so captured fixtures can be checked for parser coverage, raw object field frequency, unknown object samples, replay readiness, and tuning gaps.
+- `LocalApiStub --fixture-dir` replays captured fixtures before falling back to generated responses.
+
+## Safety Rules
+
+The project intentionally has no module for clipboard monitoring, startup persistence, ZIP mutation, PE resource updates, or external network communication. New features should preserve these boundaries.