# delairec/planet-crafter-save-tools architecture

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

- Interactive diagram: https://gitdiagram.com/delairec/planet-crafter-save-tools
- Repository: https://github.com/delairec/planet-crafter-save-tools

## Overview

Planet Crafter Save Tools is a browser-based and command-line toolkit for validating, merging, and inspecting game saves. The principal flow loads local save files, parses their sections, validates them, then either merges two saves into a downloadable result or maps a save into overview, player, power, configuration, and terraformation views. The graph includes those documented capabilities and the sampled parsing, mapping, and composition layers. Some UI wiring and unsampled use-case internals are not shown; those links are omitted or marked unverified.

Main entry points: [`packages/core-mapping/src/display/application`](https://github.com/delairec/planet-crafter-save-tools/tree/master/packages/core-mapping/src/display/application) (Display Use Cases), [`packages/core-mapping/src/save/application/UseCase.ts`](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/save/application/UseCase.ts) (Save Use Cases), [`packages/core-mapping/src/merge/controllers/MergeSaveFilesController.ts`](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/merge/controllers/MergeSaveFilesController.ts) (Merge Controller), [`packages/core-mapping/src/merge/application/MergeSaveFiles.ts`](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/merge/application/MergeSaveFiles.ts) (Merge Rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_browser["Browser Manager<br/>[app.tsx]"]
  node_merge_ui["Merge Form<br/>[MergeSection.tsx]"]
  node_loaded_hook["Loaded Save State<br/>[useLoadedSave.ts]"]
  node_merge_hook["Merged Save State<br/>[useMergedSaves.ts]"]
  node_merge_cli["Merge CLI<br/>[initMergeCli.js]"]
  node_validate_cli["Validation CLI<br/>[validate-cli.js]"]
  node_download["Merged Save File"]
  node_display_views["Save Views<br/>[index.tsx]"]
end

subgraph group_save["Save Processing"]
  node_save_sections["Parsed Save Sections<br/>[SaveSections.ts]"]
  node_parser["Section Parser"]
  node_save_usecase["Save Use Cases<br/>[UseCase.ts]"]
  node_validation["Save Validation"]
  node_validation_controller["Validation Controller"]
end

subgraph group_merge["Save Merging"]
  node_merge_controller["Merge Controller"]
  node_merge_usecase["Merge Rules<br/>[MergeSaveFiles.ts]"]
  node_merge_rules["Section Resolutions"]
  node_serializer["Save Serializer"]
end

subgraph group_display["Save Visualization"]
  node_overview_controller["Overview Controller"]
  node_display_usecases["Display Use Cases"]
  node_composition["Display Composition"]
  node_sections_reader["Section Reader"]
  node_sections_mapper["Domain Mapper"]
  node_display_domain["Game Domain Model"]
  node_display_presenters["Page Presenters"]
end

subgraph group_reference["Game Reference Data"]
  node_reference_data[("Game Reference Tables")]
end

node_user(("Save Owner"))

node_user -->|"opens locally"| node_browser
node_user -->|"runs merge"| node_merge_cli
node_user -->|"checks save"| node_validate_cli
node_browser -.->|"offers merge"| node_merge_ui
node_user -.->|"selects save"| node_loaded_hook
node_merge_ui -.->|"submits saves"| node_merge_hook
node_merge_cli -.->|"invokes merge"| node_merge_controller
node_validate_cli -.->|"invokes validation"| node_validation_controller
node_validation_controller -->|"creates use case"| node_save_usecase
node_save_usecase -.->|"parses content"| node_parser
node_parser -->|"decodes sections"| node_save_sections
node_save_usecase -.->|"validates save"| node_validation
node_merge_controller -->|"executes merge"| node_merge_usecase
node_merge_usecase -.->|"resolves conflicts"| node_merge_rules
node_merge_usecase -.->|"serializes result"| node_serializer
node_merge_controller -.->|"returns result"| node_download
node_user -.->|"requests views"| node_overview_controller
node_overview_controller -.->|"loads overview"| node_display_usecases
node_composition -->|"constructs use cases"| node_display_usecases
node_composition -->|"constructs reader"| node_sections_reader
node_display_usecases -.->|"reads save"| node_sections_reader
node_sections_reader -.->|"parses sections"| node_parser
node_sections_mapper -->|"builds entities"| node_display_domain
node_sections_mapper -->|"maps entries"| node_save_sections
node_display_usecases -.->|"presents results"| node_display_presenters
node_display_presenters -.->|"formats views"| node_display_views
node_display_usecases -->|"reads game tables"| node_reference_data

click node_browser "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/ui-save-manager/src/app.tsx"
click node_merge_ui "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/ui-save-manager/src/components/MergeSection.tsx"
click node_loaded_hook "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/ui-save-manager/src/hooks/useLoadedSave.ts"
click node_merge_hook "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/ui-save-manager/src/hooks/useMergedSaves.ts"
click node_merge_cli "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/cli-merge/cli/initMergeCli.js"
click node_validate_cli "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/cli-validate/cli/validate-cli.js"
click node_save_sections "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/save/domain/save/SaveSections.ts"
click node_parser "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/save/infrastructure/SaveSectionsParserService.ts"
click node_save_usecase "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/save/application/UseCase.ts"
click node_validation "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/save/infrastructure/SaveValidatorService.ts"
click node_validation_controller "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/validation/controllers/ValidateSaveFileController.ts"
click node_merge_controller "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/merge/controllers/MergeSaveFilesController.ts"
click node_merge_usecase "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/merge/application/MergeSaveFiles.ts"
click node_merge_rules "https://github.com/delairec/planet-crafter-save-tools/tree/master/packages/core-mapping/src/merge/domain/rules"
click node_serializer "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/merge/infrastructure/SaveSectionsSerializerService.ts"
click node_overview_controller "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/display/controllers/LoadOverviewPageController.ts"
click node_display_usecases "https://github.com/delairec/planet-crafter-save-tools/tree/master/packages/core-mapping/src/display/application"
click node_composition "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/display/composition/useCaseFactories.ts"
click node_sections_reader "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/display/infrastructure/SaveSectionsReaderService.ts"
click node_sections_mapper "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/display/infrastructure/SaveSectionsMapperService.ts"
click node_display_domain "https://github.com/delairec/planet-crafter-save-tools/tree/master/packages/core-mapping/src/display/domain/entities"
click node_display_presenters "https://github.com/delairec/planet-crafter-save-tools/tree/master/packages/core-mapping/src/display/presentation"
click node_display_views "https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/ui-save-manager/src/routes/index.tsx"
click node_reference_data "https://github.com/delairec/planet-crafter-save-tools/tree/master/packages/data-energy"

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_browser,node_merge_ui,node_loaded_hook,node_merge_hook,node_merge_cli,node_validate_cli,node_download,node_display_views toneBlue
class node_save_sections,node_parser,node_save_usecase,node_validation,node_validation_controller toneAmber
class node_merge_controller,node_merge_usecase,node_merge_rules,node_serializer toneMint
class node_overview_controller,node_display_usecases,node_composition,node_sections_reader,node_sections_mapper,node_display_domain,node_display_presenters toneRose
class node_reference_data,node_user toneIndigo
```

## Components

### User Interfaces

- [Browser Manager](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/ui-save-manager/src/app.tsx): `packages/ui-save-manager/src/app.tsx`
- [Merge Form](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/ui-save-manager/src/components/MergeSection.tsx): `packages/ui-save-manager/src/components/MergeSection.tsx`
- [Loaded Save State](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/ui-save-manager/src/hooks/useLoadedSave.ts): `packages/ui-save-manager/src/hooks/useLoadedSave.ts`
- [Merged Save State](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/ui-save-manager/src/hooks/useMergedSaves.ts): `packages/ui-save-manager/src/hooks/useMergedSaves.ts`
- [Merge CLI](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/cli-merge/cli/initMergeCli.js): `packages/cli-merge/cli/initMergeCli.js`
- [Validation CLI](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/cli-validate/cli/validate-cli.js): `packages/cli-validate/cli/validate-cli.js`
- **Merged Save File**
- [Save Views](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/ui-save-manager/src/routes/index.tsx): `packages/ui-save-manager/src/routes/index.tsx`

### Save Processing

- [Parsed Save Sections](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/save/domain/save/SaveSections.ts): `packages/core-mapping/src/save/domain/save/SaveSections.ts`
- [Section Parser](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/save/infrastructure/SaveSectionsParserService.ts): `packages/core-mapping/src/save/infrastructure/SaveSectionsParserService.ts`
- [Save Use Cases](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/save/application/UseCase.ts): `packages/core-mapping/src/save/application/UseCase.ts`
- [Save Validation](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/save/infrastructure/SaveValidatorService.ts): `packages/core-mapping/src/save/infrastructure/SaveValidatorService.ts`
- [Validation Controller](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/validation/controllers/ValidateSaveFileController.ts): `packages/core-mapping/src/validation/controllers/ValidateSaveFileController.ts`

### Save Merging

- [Merge Controller](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/merge/controllers/MergeSaveFilesController.ts): `packages/core-mapping/src/merge/controllers/MergeSaveFilesController.ts`
- [Merge Rules](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/merge/application/MergeSaveFiles.ts): `packages/core-mapping/src/merge/application/MergeSaveFiles.ts`
- [Section Resolutions](https://github.com/delairec/planet-crafter-save-tools/tree/master/packages/core-mapping/src/merge/domain/rules): `packages/core-mapping/src/merge/domain/rules`
- [Save Serializer](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/merge/infrastructure/SaveSectionsSerializerService.ts): `packages/core-mapping/src/merge/infrastructure/SaveSectionsSerializerService.ts`

### Save Visualization

- [Overview Controller](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/display/controllers/LoadOverviewPageController.ts): `packages/core-mapping/src/display/controllers/LoadOverviewPageController.ts`
- [Display Use Cases](https://github.com/delairec/planet-crafter-save-tools/tree/master/packages/core-mapping/src/display/application): `packages/core-mapping/src/display/application`
- [Display Composition](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/display/composition/useCaseFactories.ts): `packages/core-mapping/src/display/composition/useCaseFactories.ts`
- [Section Reader](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/display/infrastructure/SaveSectionsReaderService.ts): `packages/core-mapping/src/display/infrastructure/SaveSectionsReaderService.ts`
- [Domain Mapper](https://github.com/delairec/planet-crafter-save-tools/blob/master/packages/core-mapping/src/display/infrastructure/SaveSectionsMapperService.ts): `packages/core-mapping/src/display/infrastructure/SaveSectionsMapperService.ts`
- [Game Domain Model](https://github.com/delairec/planet-crafter-save-tools/tree/master/packages/core-mapping/src/display/domain/entities): `packages/core-mapping/src/display/domain/entities`
- [Page Presenters](https://github.com/delairec/planet-crafter-save-tools/tree/master/packages/core-mapping/src/display/presentation): `packages/core-mapping/src/display/presentation`

### Game Reference Data

- [Game Reference Tables](https://github.com/delairec/planet-crafter-save-tools/tree/master/packages/data-energy): `packages/data-energy`

### Other components

- **Save Owner**

## Connections

- Save Owner → Browser Manager: opens locally (evidence: `README.md`)
- Save Owner → Merge CLI: runs merge (evidence: `README.md`)
- Save Owner → Validation CLI: checks save (evidence: `README.md`)
- Browser Manager → Merge Form: offers merge
- Save Owner → Loaded Save State: selects save
- Merge Form → Merged Save State: submits saves
- Merge CLI → Merge Controller: invokes merge
- Validation CLI → Validation Controller: invokes validation
- Validation Controller → Save Use Cases: creates use case (evidence: `packages/core-mapping/src/validation/controllers/ValidateSaveFileController.ts`)
- Save Use Cases → Section Parser: parses content
- Section Parser → Parsed Save Sections: decodes sections (evidence: `packages/core-mapping/src/save/infrastructure/SaveSectionsParserService.ts`)
- Save Use Cases → Save Validation: validates save
- Merge Controller → Merge Rules: executes merge (evidence: `packages/core-mapping/src/merge/controllers/MergeSaveFilesController.ts`)
- Merge Rules → Section Resolutions: resolves conflicts
- Merge Rules → Save Serializer: serializes result
- Merge Controller → Merged Save File: returns result
- Save Owner → Overview Controller: requests views
- Overview Controller → Display Use Cases: loads overview (evidence: `packages/core-mapping/src/display/controllers/LoadOverviewPageController.ts`)
- Display Composition → Display Use Cases: constructs use cases (evidence: `packages/core-mapping/src/display/composition/useCaseFactories.ts`)
- Display Composition → Section Reader: constructs reader (evidence: `packages/core-mapping/src/display/composition/useCaseFactories.ts`)
- Display Use Cases → Section Reader: reads save
- Section Reader → Section Parser: parses sections
- Domain Mapper → Game Domain Model: builds entities (evidence: `packages/core-mapping/src/display/infrastructure/SaveSectionsMapperService.ts`)
- Domain Mapper → Parsed Save Sections: maps entries (evidence: `packages/core-mapping/src/display/infrastructure/SaveSectionsMapperService.ts`)
- Display Use Cases → Page Presenters: presents results
- Page Presenters → Save Views: formats views
- Display Use Cases → Game Reference Tables: reads game tables