# arbom/sharppddl architecture

> Architecture diagram of the GitHub repository arbom/sharppddl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arbom/sharppddl
- Repository: https://github.com/arbom/sharppddl

## Overview

1. SharpPDDL is a reusable C# class library, not a single application. The repository’s main deliverable is the `SharpPDDL` library, with several console-style example projects under `Examples/` that demonstrate how to model and solve planning problems.

2. The architectural core is a PDDL/GOAP-style planner built directly in C# using expression trees and lambdas. Instead of parsing `.pddl` files, users define domains, actions, preconditions, effects, goals, and costs programmatically against their own domain classes.

3. The model layer is split across types that represent domain objects and their metadata: `ObjectPDDL`, `TypesPDDL`, `SingleType`, `Value`, `Parametr`, `ElementInObjectPDDL`, and related helpers. The README’s constraint that state values must be value types is important because the planner relies on equality/comparison over generated state representations.

4. Actions are the main public abstraction. The `ActionPDDL` and `ActionPDDL/*` files cover action definitions, parameter binding, action “sentences” for human-readable output, and action checking/visualization support. An action can carry both logical conditions and executable side effects.

5. Preconditions, effects, goals, and costs each have their own subsystem. The repository separates these into `PreconditionPDDL`, `EffectPDDL`, `GoalsPDDP`, and `ActionCost`, with lambda-based variants for user-supplied expressions. This keeps the planner generic while letting the user describe domain-specific logic in code.

6. Planning/search appears to be graph-based rather than a simple tree expansion. The `CrisscrossesGenerate` and `Collections/Crisscross*` files suggest state-space expansion, duplicate-state reduction, and goal checking over a cross-linked exploration structure. Supporting node types like `TreeNode`, `ChainStruct`, and comparers handle traversal, equality, and state deduplication.

7. The planner pipeline is centered around domain realization and search orchestration. `DomainPDDLtaskRealization`, `DomainPlanner`, `DomeinPDDL`, `Executor`, and `PossibleState` are the likely top-level coordination points: define domain, expand reachable states, reduce them, test against the goal, then emit an ordered plan.

8. Execution is a separate concern from planning. The `Execution/` folder contains expression execution and action execution helpers, plus exception types for precondition failures. This suggests the library can both compute a plan and optionally replay it against live objects through user-provided callbacks.

9. Visualization and export are first-class utilities. `DGML.cs`, `TypesPDDLVisualization.cs`, `ActionPDDL/ActionsVisualization.cs`, and `CrisscrossesGenerate/CrisscrossesVisualization.cs` indicate support for inspecting domains, actions, and search graphs, likely for debugging or documentation.

10. The `Thumbnails/` folder indicates an internal intermediate representation of object instances and types. The README’s Hanoi diagram shows these “thumbnail” objects being used to derive state-space nodes from user classes, which is a key boundary between the user’s domain model and the planner’s internal model.

11. The examples are separate consumer applications, each modeling a classic planning problem: 15-puzzle, Hanoi Tower, peg solitaire, river crossing, travelling salesman, and water pouring. They illustrate the same flow: define domain classes, declare actions with preconditions/effects/costs, invoke the planner, and print or execute the resulting plan.

12. One example, travelling salesman, also shows an external data dependency through `CitiesAPI` for distance lookup. That dependency exists only in the example layer; the core library itself is intended to be self-contained and uses only the C# standard library.

13. Build and delivery are straightforward: the solution contains a single library project plus example projects, with GitHub Actions workflows for .NET build validation and line-of-code reporting. The repo is therefore organized around a core planning engine with thin sample clients, not around a server, UI, or distributed system.

Main entry points: [`SharpPDDL/ActionPDDL/ActionPDDL.cs`](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/ActionPDDL/ActionPDDL.cs) (Actions), [`SharpPDDL/CrisscrossesGenerate/CrisscrossGenerator.cs`](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/CrisscrossesGenerate/CrisscrossGenerator.cs) (Search graph), [`SharpPDDL/DomainPlanner.cs`](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/DomainPlanner.cs) (Planner), [`SharpPDDL/DGML.cs`](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/DGML.cs) (Visualization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["SharpPDDL core"]
  node_object_model["Domain model<br/>C# types<br/>[ObjectPDDL.cs]"]
  node_thumbnails["Thumbnails<br/>IR builder<br/>[ThumbnailObject.cs]"]
  node_actions["Actions<br/>action model<br/>[ActionPDDL.cs]"]
  node_preconditions["Preconditions<br/>condition model"]
  node_effects["Effects<br/>state update<br/>[EffectPDDL.cs]"]
  node_goals["Goals<br/>goal model<br/>[GoalPDDL.cs]"]
  node_costs["Costs<br/>action cost<br/>[ActionCost.cs]"]
  node_planner["Planner<br/>orchestrator<br/>[DomainPlanner.cs]"]
  node_search["Search graph<br/>state-space search"]
  node_collections["State collections<br/>graph structs<br/>[Crisscross.cs]"]
  node_executor["Executor<br/>runtime<br/>[Executor.cs]"]
  node_execution["Execution helpers<br/>runtime exec"]
  node_visualization["Visualization<br/>export<br/>[DGML.cs]"]
  node_state["Possible state<br/>state snapshot<br/>[PossibleState.cs]"]
end

subgraph group_examples["Examples"]
  node_examples_suite["Puzzle examples<br/>sample apps<br/>[README.md]"]
  node_tsp_api["Cities API<br/>example data<br/>[CitiesAPI.cs]"]
end

subgraph group_automation["Automation"]
  node_build_ci["Build CI<br/>workflows<br/>[dotnet.yml]"]
end

node_thumbnails -->|"derives"| node_object_model
node_object_model -->|"binds"| node_actions
node_actions -->|"uses"| node_preconditions
node_actions -->|"applies"| node_effects
node_actions -->|"prices"| node_costs
node_goals -->|"targets"| node_planner
node_planner -->|"expands"| node_search
node_search -->|"stores"| node_collections
node_search -->|"materializes"| node_state
node_search -->|"checks"| node_goals
node_planner -->|"returns plan to"| node_executor
node_executor -->|"invokes"| node_execution
node_actions -->|"supports"| node_execution
node_visualization -->|"renders"| node_actions
node_visualization -->|"renders"| node_search
node_visualization -->|"renders"| node_object_model
node_examples_suite -->|"consumes"| node_planner
node_examples_suite -->|"uses"| node_tsp_api
node_build_ci -.->|"validates"| node_examples_suite

click node_object_model "https://github.com/arbom/sharppddl/blob/master/SharpPDDL/ObjectPDDL.cs"
click node_thumbnails "https://github.com/arbom/sharppddl/blob/master/SharpPDDL/Thumbnails/ThumbnailObject.cs"
click node_actions "https://github.com/arbom/sharppddl/blob/master/SharpPDDL/ActionPDDL/ActionPDDL.cs"
click node_preconditions "https://github.com/arbom/sharppddl/blob/master/SharpPDDL/PreconditionPDDL/PreconditionPDDL.cs"
click node_effects "https://github.com/arbom/sharppddl/blob/master/SharpPDDL/EffectPDDL/EffectPDDL.cs"
click node_goals "https://github.com/arbom/sharppddl/blob/master/SharpPDDL/GoalsPDDP/GoalPDDL.cs"
click node_costs "https://github.com/arbom/sharppddl/blob/master/SharpPDDL/ActionCost/ActionCost.cs"
click node_planner "https://github.com/arbom/sharppddl/blob/master/SharpPDDL/DomainPlanner.cs"
click node_search "https://github.com/arbom/sharppddl/blob/master/SharpPDDL/CrisscrossesGenerate/CrisscrossGenerator.cs"
click node_collections "https://github.com/arbom/sharppddl/blob/master/SharpPDDL/Collections/Crisscross.cs"
click node_executor "https://github.com/arbom/sharppddl/blob/master/SharpPDDL/Executor.cs"
click node_execution "https://github.com/arbom/sharppddl/blob/master/SharpPDDL/Execution/ExpressionExecution.cs"
click node_visualization "https://github.com/arbom/sharppddl/blob/master/SharpPDDL/DGML.cs"
click node_state "https://github.com/arbom/sharppddl/blob/master/SharpPDDL/PossibleState.cs"
click node_examples_suite "https://github.com/arbom/sharppddl/blob/master/Examples/README.md"
click node_tsp_api "https://github.com/arbom/sharppddl/blob/master/Examples/Travelling Salesman Problem/CitiesAPI.cs"
click node_build_ci "https://github.com/arbom/sharppddl/blob/master/.github/workflows/dotnet.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_object_model,node_thumbnails,node_actions,node_preconditions,node_effects,node_goals,node_costs,node_planner,node_search,node_collections,node_executor,node_execution,node_visualization,node_state toneBlue
class node_examples_suite,node_tsp_api toneAmber
class node_build_ci toneMint
```

## Components

### SharpPDDL core

Reusable planning library and its internal subsystems.

- [Domain model](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/ObjectPDDL.cs): C# types · User domain objects, types, values, parameters, and member metadata. · `SharpPDDL/ObjectPDDL.cs`
- [Thumbnails](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/Thumbnails/ThumbnailObject.cs): IR builder · Intermediate object/type representations used to derive planner state from user classes. · `SharpPDDL/Thumbnails/ThumbnailObject.cs`
- [Actions](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/ActionPDDL/ActionPDDL.cs): action model · Action definitions, bindings, human-readable sentences, and action checking. · `SharpPDDL/ActionPDDL/ActionPDDL.cs`
- [Preconditions](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/PreconditionPDDL/PreconditionPDDL.cs): condition model · Logical preconditions and lambda-based condition variants. · `SharpPDDL/PreconditionPDDL/PreconditionPDDL.cs`
- [Effects](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/EffectPDDL/EffectPDDL.cs): state update · Action effects, including lambda and pointer-based variants. · `SharpPDDL/EffectPDDL/EffectPDDL.cs`
- [Goals](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/GoalsPDDP/GoalPDDL.cs): goal model · Goal definitions and goal checking helpers. · `SharpPDDL/GoalsPDDP/GoalPDDL.cs`
- [Costs](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/ActionCost/ActionCost.cs): action cost · Action cost definitions and lambda-based cost evaluation. · `SharpPDDL/ActionCost/ActionCost.cs`
- [Planner](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/DomainPlanner.cs): orchestrator · Domain realization and top-level planning coordination. · `SharpPDDL/DomainPlanner.cs`
- [Search graph](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/CrisscrossesGenerate/CrisscrossGenerator.cs): state-space search · Crisscross generation, reduction, goal checks, and duplicate-state management. · `SharpPDDL/CrisscrossesGenerate/CrisscrossGenerator.cs`
- [State collections](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/Collections/Crisscross.cs): graph structs · Tree and crisscross structures, comparers, and traversal helpers used by search. · `SharpPDDL/Collections/Crisscross.cs`
- [Executor](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/Executor.cs): runtime · Expression execution and action replay helpers for applying plans. · `SharpPDDL/Executor.cs`
- [Execution helpers](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/Execution/ExpressionExecution.cs): runtime exec · Precondition failures, expression execution, and whole-action execution wrappers. · `SharpPDDL/Execution/ExpressionExecution.cs`
- [Visualization](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/DGML.cs): export · DGML and visualization helpers for domains, actions, and search graphs. · `SharpPDDL/DGML.cs`
- [Possible state](https://github.com/arbom/sharppddl/blob/master/SharpPDDL/PossibleState.cs): state snapshot · Computed planner state representation used during expansion and comparison. · `SharpPDDL/PossibleState.cs`

### Examples

Console-style consumer projects demonstrating the planner.

- [Puzzle examples](https://github.com/arbom/sharppddl/blob/master/Examples/README.md): sample apps · Console examples for classic planning problems and external data integration. · `Examples/README.md`
- [Cities API](https://github.com/arbom/sharppddl/blob/HEAD/Examples/Travelling%20Salesman%20Problem/CitiesAPI.cs): example data · External distance lookup used by the travelling salesman example. · `Examples/Travelling Salesman Problem/CitiesAPI.cs`

### Automation

Build and repository maintenance workflows.

- [Build CI](https://github.com/arbom/sharppddl/blob/master/.github/workflows/dotnet.yml): workflows · Repository workflows for .NET build validation and line-of-code reporting. · `.github/workflows/dotnet.yml`

## Connections

- Thumbnails → Domain model: derives · Turns user domain classes into planner-facing object/type metadata.
- Domain model → Actions: binds · Actions are declared against the user domain model and its parameters.
- Actions → Preconditions: uses · Each action may carry logical conditions that must hold before execution.
- Actions → Effects: applies · Actions define how state changes after preconditions succeed.
- Actions → Costs: prices · Actions can contribute search cost or heuristic weight.
- Goals → Planner: targets · The planner searches for states that satisfy goal definitions.
- Planner → Search graph: expands · Top-level orchestration delegates reachable-state exploration to search generation.
- Search graph → State collections: stores · Search uses graph/tree structures and comparers to manage explored states.
- Search graph → Possible state: materializes · Expansion produces candidate planner states for comparison and goal tests.
- Search graph → Goals: checks · Generated states are tested against the goal subsystem.
- Planner → Executor: returns plan to · A found plan can be replayed against live objects through execution.
- Executor → Execution helpers: invokes · Execution helpers run expressions and surface precondition failures.
- Actions → Execution helpers: supports · Action definitions include executable side-effect pathways.
- Visualization → Actions: renders · Action structures can be exported for inspection.
- Visualization → Search graph: renders · Search graphs and crisscross structures can be visualized.
- Visualization → Domain model: renders · Domain/type metadata can be exported as diagrams.
- Puzzle examples → Planner: consumes · Examples define domains and call into the core planner library.
- Puzzle examples → Cities API: uses · The travelling salesman sample depends on external distance data.
- Build CI → Puzzle examples: validates · Workflows build the library and example projects.
