---
name: ue5-architecture
description: UE5.6/UE5.7 architecture planning and module boundary design for Unreal projects. Use when requests involve module layout, Build.cs dependencies, reflection exposure strategy, Public/Private API boundaries, naming conventions, and preventing circular dependencies.
---

# Quick Start
- Collect current module list, `*.Build.cs`, and major gameplay/UI systems.
- Propose one target module graph before writing code.
- Output module responsibilities and ownership in a table.

# Workflow
- Identify runtime, editor, UI, networking, and data modules from current codebase.
- Define Public API for each module as minimal headers and Blueprint surface.
- Define Private implementation boundaries and include rules.
- Define `PublicDependencyModuleNames` and `PrivateDependencyModuleNames` per module.
- Report risks: circular includes, over-exposed reflection types, and cross-layer references.

# Constraints
- Keep `UCLASS/USTRUCT/UENUM` only where reflection is required.
- Prefer forward declarations in headers; include concrete headers in `.cpp`.
- Do not move types across modules without listing migration impact.
- Keep naming aligned with Unreal conventions (`U`, `A`, `F`, `E` prefixes).

# Failure Handling
- If ownership of a class is ambiguous, place it in runtime module first and log a TODO to split after usage mapping.
- If dependency graph becomes cyclic, extract shared contracts into a thin common module.
- If Build.cs dependencies are uncertain, choose minimal set and verify compile paths immediately.

# Escalation
- Escalate when a refactor requires asset redirectors, class renames, or package path migration.
- Escalate when module split changes public Blueprint class paths used by existing content.