# Target Architecture

This document describes the intended medium-term architecture for the project.

## Relationship To The Current Code

- `docs/technical/architecture.md` is the source of truth for what exists now.
- This document is intentionally aspirational.
- If this document conflicts with the current implementation, the current implementation wins.

## Goals

- Keep `App.tsx` small and orchestration-oriented.
- Separate production world code from debug-only runtime paths.
- Keep one clear source of truth per concern.
- Grow gameplay systems incrementally instead of prebuilding empty architecture.

## Intended Layers

### App Layer

- `App.tsx` mounts the canvas scene and top-level HTML overlays.
- It should stay thin and avoid gameplay logic.

### World Layer

- `src/world/` should contain production scene composition and production scene objects.
- Expected responsibilities:
  - world composition
  - map, environment, lighting
  - player controller
  - production interaction anchors
  - production post-processing, if needed

### Debug Layer

- Debug-only scenes and tooling should be isolated from the production world path.
- Expected responsibilities:
  - `lil-gui`
  - performance overlay
  - scene helpers
  - free camera and calibration controls
  - temporary test scenes used during development

### UI Layer

- `src/components/ui/` should contain player-facing HTML overlays.
- Expected future examples:
  - crosshair
  - loading flow
  - mission HUD
  - narrative overlays

### Gameplay Layer

- As the project grows, gameplay state can move toward a clearer orchestration layer.
- Likely future concerns:
  - missions
  - zones
  - cinematics
  - dialogue
  - audio
  - interactions

## Rules

- Prefer direct, working code over speculative scaffolding.
- Shared types should stay close to their domain until they have multiple real consumers.
- Avoid creating new managers or service layers without an active runtime need.
- Debug-only runtime paths should be clearly marked and easy to remove later.