foundation-architecture

name	foundation-architecture
description	Foundational architecture skill for Godot workflows. Defines authority boundaries, composition strategy, scene ownership, command pathways, and replaceability constraints.
tier	core
godot_version	4.6+
doc_anchors	["godot-docs/tutorials/best_practices/scene_organization.rst","godot-docs/tutorials/best_practices/scenes_versus_scripts.rst","godot-docs/tutorials/best_practices/project_organization.rst"]
tags	["architecture","authority","composition"]
depends_on	[]

Foundation Architecture

Use When

• Designing any non-trivial Godot feature.
• Refactoring systems with coupling or unclear ownership.
• Planning plugin/module boundaries.

Outcomes

• Mutable state has explicit ownership and mutation pathways.
• Module boundaries and replacement points are documented.
• Architecture decisions are testable before implementation begins.

Required Rules

• Define one authority owner for every mutable state surface.
• Route mutations through explicit command/result boundaries.
• Prefer composition over inheritance for gameplay systems.
• Keep scene ownership boundaries stable under subtree refactors.

Workflow

1. Map modules and identify authoritative owners.
2. Define command inputs, outputs, and invariants per owner.
3. Declare dependency direction and replaceability constraints.
4. Mark deterministic boundaries where state ordering matters.
5. Validate architecture against planned refactors and test strategy.

Validation

• Architecture review confirms no ambiguous mutable-state ownership.
• At least one mutation path is traced end-to-end and remains single-writer.
• Planned subtree move does not require cross-cutting rewiring.

Failure Modes

• Multiple systems mutate the same state without arbitration.
• UI/presentation listeners mutate simulation state indirectly.
• Module boundaries depend on fragile node-path coupling.

Local Doc Anchors

• godot-docs/tutorials/best_practices/scene_organization.rst
• godot-docs/tutorials/best_practices/scenes_versus_scripts.rst
• godot-docs/tutorials/best_practices/project_organization.rst