71 lines
2.0 KiB
Markdown
71 lines
2.0 KiB
Markdown
# 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.
|