refactor: tighten project structure and strengthen tooling

docs/technical/target-architecture.md

@@ -0,0 +1,61 @@
+# Target Architecture
+
+This document describes the intended medium-term architecture for the project.
+
+## Goals
+
+- Keep `main` stable, `develop` as the integration branch, and `feat/*` for feature work.
+- Keep the runtime split between scene composition, gameplay systems, debug tooling, and HTML UI.
+- Keep one clear source of truth per concern.
+
+## Intended Layers
+
+### App Layer
+
+- `App.tsx` should stay small and orchestration-oriented.
+- It should mount the canvas scene and top-level HTML overlays.
+
+### World Layer
+
+- `src/world/` should contain only production scene objects and scene composition.
+- Expected responsibilities:
+  - world composition
+  - map/environment/lighting
+  - player controller
+  - zones
+  - post-processing used in production
+
+### Debug Layer
+
+- `src/utils/debug/` should contain only developer tooling.
+- Expected responsibilities:
+  - `lil-gui`
+  - performance overlay
+  - scene helpers
+  - free camera and calibration controls
+
+### UI Layer
+
+- `src/components/ui/` should contain HTML overlays used by the player.
+- Expected examples:
+  - crosshair
+  - loading screen
+  - mission HUD
+  - narrative overlays
+
+### Gameplay Layer
+
+- Gameplay state should eventually live in dedicated managers and thin hooks once those systems exist.
+- Expected future concerns:
+  - missions
+  - zones
+  - cinematics
+  - audio
+  - interactions
+
+## Rules
+
+- `world/` should not contain debug-only tooling.
+- `debug/` should not own production gameplay systems.
+- Shared types should live close to their domain and move outward only when they gain multiple real consumers.
+- New files should only be created when they have an active runtime purpose.