IMX6U-Game/docs/ARCHITECTURE_BOUNDARIES.md

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.