# Architecture Boundaries

This document defines the boundary between **Core** (engine library) and **Apps** (application layer) in the IMX6U-Game project.

## Public API (App may include)

App code should only include headers from these Core subdirectories:

| Subdirectory | Contents |
|---|---|
| `Core/RenderData/` | Color, Image, Sprite, Tilemap, BoundingBox, BitmapFont |
| `Core/Math/` | Vector2, Vector3, Vector4, Matrix4x4, MathUtil |
| `Core/Platform/` | Display, ButtonInput, IKeyboardState, PointerInput, AudioInput, AudioOutput, IPhotoSensor, TimeSource, Timer, DefaultHardware |
| `Core/Draw2D/` | DrawContext |

## Private API (App must not include)

These subdirectories are Core internals. App code must not include headers from them or reference their types directly.

| Subdirectory | Contents |
|---|---|
| `Core/Core/` | FrameBuffer, DepthBuffer, Renderer |
| `Core/Scene/` | Camera, Mesh, Model, Transform, Vertex |
| `Core/Rasterizer/` | Rasterizer, TriangleRasterizer |
| `Core/Shading/` | BlinnPhongShader, ShaderTypes |

## Rules

1. **Dependency direction**: Core must never depend on Apps. Apps depend on Core through the public API only.
2. **Platform isolation**: No `#include <SDL.h>`, `#include <alsa*>`, or `#include <linux/input.h>` outside `src/Core/Platform/`. App code accesses hardware through Platform interfaces (`IButtonInput`, `IKeyboardState`, `IPointerInput`, etc.).
3. **Interface usage**: App code should use abstract interfaces from Platform, not concrete implementation classes. Use `DefaultHardware.h` typedefs when you need a concrete type.
4. **No Core private types in App headers**: App headers must not forward-declare or reference types from private Core subdirectories.

## Violation Checklist

Use this during code review:

- [ ] No `#include <SDL.h>` outside `src/Core/Platform/`
- [ ] No `#include <alsa*>` outside `src/Core/Platform/`
- [ ] No `#include <linux/input.h>` outside `src/Core/Platform/`
- [ ] App code includes only from public subdirectories (RenderData, Math, Platform, Draw2D)
- [ ] No App header forward-declares or references Core private types (Scene, Rasterizer, Shading, Core/Core)
- [ ] Core source files contain no references to App namespaces or types

## Input Interface Architecture

The Platform layer provides separate interfaces for different input modalities:

| Interface | Purpose | Backend (Desktop) | Backend (Embedded) |
|---|---|---|---|
| `IButtonInput` | Single physical button | `SdlKeyboardButtonInput` | `EvdevButtonInput` |
| `IKeyboardState` | Multi-key keyboard state | `SdlKeyboardState` | `EvdevKeyboardState` (stub) |
| `IPointerInput` | Mouse/touch pointer | `SdlPointerInput` | `EvdevTouchInput` |
| `IPhotoSensor` | Light sensor | `SdlPhotoSensor` | `LinuxPhotoSensor` |

App code accesses these through `DefaultHardware.h` typedefs (`DefaultButtonInput`, `DefaultKeyboardState`, etc.).

### Input Priority

When multiple input sources are active simultaneously, keyboard input takes priority over pointer input for movement direction. This is an intentional design choice for desktop usability.

### Future Consolidation

When a 4th input modality is added (e.g., gamepad), consider consolidating `IButtonInput*` + `IKeyboardState*` + `IPointerInput*` into a single `IInputState` interface to prevent parameter accumulation in application classes.