Architecture
The SaveAndLoadPresetManager is a transport pipeline: validate, normalize, version-gate, and return a schema-agnostic payload envelope.
Layered Design
Responsibilities by Layer
| Layer | Responsibility | Does NOT Do |
|---|---|---|
| Validator | Validate payload/envelope shape and upload file type | Module schema parsing |
| Serializer | Build/serialize transport and generate deterministic filenames | Domain transformations |
| Parser | Parse JSON text/file and orchestrate transport validation pipeline | Module form reset |
| Migration | Enforce supported transport version | Domain migrations |
| Error Adapter | Map typed errors to deterministic user messages | UI rendering |
Boundary Model
The module enforces a strict boundary between transport validity and domain validity.
| Boundary | Owner | Validation Scope |
|---|---|---|
| Transport boundary | SaveAndLoadPresetManager | File type, JSON shape, contract version, resource compatibility |
| Domain boundary | Caller module | Schema-safe payload for form/domain rules |
This keeps transport utilities reusable across modules while letting each module enforce its own schema invariants.
Versioning Model
- Transport version is global (
PRESET_TRANSPORT_VERSION) PresetMigration.migrate()currently supports only the current version- Unsupported versions throw
UnsupportedPresetVersionError
When future versions are introduced, migration logic extends in migration.ts without changing caller integration contracts.
Filename Strategy
Filename generation is deterministic and context-aware:
- Build canonical base name:
site-siteId-resource-timestamp.json - If user provides
presetName, prefix it:
presetName-site-siteId-resource-timestamp.json - Segments are sanitized to lowercase slug format
This preserves traceability while honoring user naming intent.
Error Strategy
Typed transport errors are converted to deterministic UI-safe messages via getPresetUserMessage(error).
| Error Type | Message Outcome |
|---|---|
InvalidPresetResourceError |
Resource mismatch message |
UnsupportedPresetVersionError |
Version unsupported message |
CorruptedPresetError |
Corrupted/unreadable message |
InvalidPresetError |
Original error message |
| Unknown error | Generic fallback message |