Architecture Overview (6.0)

The core architectural principles of GridPlacement 6.0: Services, Workflows, and Adapters.

sort Weight: 10

6.0 follows a Service-Based Architecture designed for cross-engine portability and strict testability. The system is divided into an engine-agnostic Core (Logic) and engine-specific Adapters (Presentation).

1. The Three-Layer Model

The architecture is organized into three distinct layers to ensure separation of concerns:

graph TD
    subgraph EngineLayer [Game Engine Layer]
        A[Scenes & UI] -->|Commands| B[Engine Bridges]
        B -->|Signals/Events| A
    end

    subgraph CoreAdapters [Core Adapter Layer]
        B -->|Core Types| C[Logic Adapters]
        C -->|Domain Events| B
    end

    subgraph CoreLogic [Pure Logic Layer]
        C -->|Coordination| D[Workflows]
        D -->|Operations| E[Domain Services]
        E -->|State Mutation| F[System State]
        E -->|Broadcast| G[Event Bus]
    end

Layer Responsibilities

LayerComponentSuffixResponsibility
LogicServicesServiceAtomic business rules and algorithms (e.g., Pathfinding, Validation).
LogicWorkflowsWorkflow(Formerly Orchestrators) Coordinates multiple services to fulfill a user goal.
LogicStateStatePure-data POCOs representing the system status.
AdapterCore AdaptersAdapterLogic-layer translation between raw inputs and system workflows.
EngineBridgesBridgeEngine-facing Nodes/MonoBehaviours that convert engine types (Vectors, etc).

2. Core Architectural Principles

Engine Agnosticism

The Core contains zero references to engine-specific namespaces like Godot or UnityEngine. All logic operates on Core Types (e.g., CoreVector2, CoreRect2I).

Authoritative Targeting State

The TargetingState is the single source of truth for the entire system. Whether in BUILD, MOVE, or SELECT mode, all components query this centralized state to understand the active focus.

Snapshot-Based Observation

To prevent accidental side-effects, external systems (UI, VFX) and tests consume Snapshots. A Snapshot is a read-only, point-in-time copy of the system state.

3. Communication Patterns

uses a tiered approach to balance performance with decoupling:

  1. Top-Down Commands: Direct method calls from Bridges to Workflows, and Workflows to Services.
  2. Bottom-Up Events (Event Bus): Services publish Domain Events to the GPEventBus. Independent systems (Audio, UI) listen to this bus to react without coupling.
  3. Local Whispering (C# Events): Used for high-performance coordination between a Service and its internal sub-managers.

4. Dependency Injection & Composition

In 6.0, composition is Registry-Based via the ServiceRegistry.

  • User Scopes: Supports multitenancy (multiple independent grids) via IUserScope.
  • Interface Injection: Components depend on interfaces (e.g., IManipulationService) rather than concrete implementations.
  • Engine Seams: The IConfigurationProvider interface allows the Core to consume data from Godot Resources (or other engine equivalents) without coupling to the asset types.

5. Modern Data Flow

The system distinguishes between Active Requests and Reactive Events:

  1. Requests: UI or Input triggers a request via a Workflow Adapter.
  2. Orchestration: The Workflow coordinates the necessary services.
  3. Mutation: Services update the System State.
  4. Broadcast: The Event Bus notifies the world of the change.
  5. Reaction: Presenters update Godot nodes based on event payloads.

Last updated: 2025-12-22