# vortiago/sh7pad architecture

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

- Interactive diagram: https://gitdiagram.com/vortiago/sh7pad
- Repository: https://github.com/vortiago/sh7pad

## Overview

1. **What this repo is**
   - `sh7pad` is a fully client-side browser app for viewing, creating, editing, previewing, importing, and exporting `.sh7` decorative-stitch files.
   - There is no backend: all parsing, editing, preview rendering, storage, and export happen in the browser.

2. **Top-level architecture**
   - The app is split into three main layers:
     - `src/parser` for reading and validating existing `.sh7` files.
     - `src/creator` for the project/domain model and stitch-generation logic.
     - `src/ui/creator` for the interactive editor, preview, side panels, dialogs, and interaction handling.
   - `src/shared` contains geometry helpers shared between parser and creator logic.

3. **Core domain model**
   - The central object is the “project,” which represents the in-progress design shown in both panes.
   - Project-related modules in `src/creator` handle metadata, invariants, migration, sample creation, repository/store access, and type definitions.
   - This is the boundary where user intent lives: points, segments, stitch settings, manual stitches, and export settings.

4. **Import path**
   - `.sh7` files are parsed through `src/parser/parseFile.ts`, `parseHeader.ts`, `parseChunks.ts`, and the stitch/satin parsers.
   - Validation is explicit and layered under `src/parser/validate/*`, which checks headers, records, chunks, metadata, satin payloads, and version-specific constraints.
   - The parser converts raw bytes into validated structures that can be turned into a project or inspected as file data.

5. **Design-mode stitch generation**
   - The design editor does not store machine stitches directly; it stores geometric intent.
   - `src/creator/pipeline/*` converts that intent into stitch output:
     - segment reduction and stitching,
     - carriage planning,
     - foot tracking,
     - multi-block emission,
     - final design encoding.
   - Satin-specific logic is a major subdomain: the app generates zigzag fill inside satin cones and other stitch sequences from higher-level shapes.

6. **Manual mode**
   - Manual mode bypasses some of the design-mode opinionated generation and lets the user place individual needle drops and jump stitches.
   - This mode exists for patterns that are easier to author as explicit stitch sequences than as vector segments.
   - It is a separate editing path, but it still feeds the same project/export pipeline.

7. **Preview and playback**
   - The preview pane simulates the stitched result rather than editing geometry.
   - It renders fabric, thread, repeated motifs, and a transport scrubber so the user can step through the stitch sequence.
   - Preview code lives under `src/ui/creator/preview`, with scene/render modules that consume the project’s generated stitch stream.

8. **Editor UI composition**
   - The editor is composed of many small UI subsystems: canvas interaction, keyboard shortcuts, pan/zoom, rulers, sidebar, toolbar, inspector peek, bottom sheet, context menus, toasts, and modals.
   - `src/ui/creator/editor/*` handles the canvas interaction and rendering model; `src/ui/creator/canvasGesture/*` and `canvasCamera/*` handle touch/pointer gestures and viewport control.
   - The layout is responsive and mode-driven, so the same project can be edited in different viewport arrangements.

9. **State and rendering flow**
   - UI state is separated from project state in `src/ui/creator/store/*`.
   - The UI store schedules re-rendering, manages layout attributes, and tracks transport state for preview playback.
   - This means interaction events update stores first, then the editor/preview canvases re-render from state rather than directly mutating DOM imperatively.

10. **Persistence and local repository**
    - Projects persist in IndexedDB through `src/creator/projectStore.ts` and related repository modules.
    - This supports offline use and keeps the “recent projects / saved projects” experience entirely local.
    - Since there is no server, the browser store is the only persistence boundary.

11. **Export formats**
    - The app exports native `.sh7` binary files and `.sh7c.json` project wrappers.
    - Export logic is split between JSON serialization, binary encoding, and SH7-specific limits/constants in `src/creator/sh7*`.
    - Import/export is the main data boundary between the app’s editable project model and the machine-readable embroidery format.

12. **Format and protocol foundation**
    - `src/format` contains lower-level chunk schema and record codecs used by the parser/encoder.
    - The repo includes a reverse-engineered format reference in `FORMAT.md` and a Kaitai Struct subset in `docs/format.ksy`, which are important because the binary format is not an external official SDK.
    - Cross-format research in `docs/research/` supports compatibility and reverse engineering work.

13. **Quality and delivery**
    - The project is built with Vite and TypeScript, tested with Vitest, and end-to-end checked with Playwright.
    - GitHub Actions cover CI, accessibility checks, and Pages deployment, which fits the app’s static-client architecture.

Main entry points: [`src/creator/project.ts`](https://github.com/vortiago/sh7pad/blob/main/src/creator/project.ts) (Project model), [`src/creator/pipeline/stitch.ts`](https://github.com/vortiago/sh7pad/blob/main/src/creator/pipeline/stitch.ts) (Stitch pipeline), [`src/ui/creator/store/uiStore.ts`](https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/store/uiStore.ts) (UI store), [`src/ui/creator/editor/index.ts`](https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/editor/index.ts) (Editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Docs & research"]
  node_docs_format_md["FORMAT.md<br/>format reference<br/>[FORMAT.md]"]
  node_docs_format_ksy["Kaitai spec<br/>format spec<br/>[format.ksy]"]
end

subgraph group_format["Format core"]
  node_format_chunk_schema["Chunk schema<br/>codec schema<br/>[chunkSchema.ts]"]
  node_format_record_codec["Record codec<br/>binary codec<br/>[recordCodec.ts]"]
end

subgraph group_parser["Import parser"]
  node_parser_file["File parse<br/>[parseFile.ts]"]
  node_parser_header["Header parse<br/>[parseHeader.ts]"]
  node_parser_chunks["Chunk parse<br/>[parseChunks.ts]"]
  node_parser_stitches["Stitch parse<br/>[parseStitches.ts]"]
  node_parser_satin["Satin parse<br/>[parseSatin.ts]"]
  node_parser_validate["Validation"]
end

subgraph group_creator["Project engine"]
  node_creator_project["Project model<br/>domain model<br/>[project.ts]"]
  node_creator_types["Project types<br/>[types.ts]"]
  node_creator_pipeline["Stitch pipeline<br/>generation pipeline<br/>[stitch.ts]"]
  node_creator_encode_design["Encode design<br/>encoder<br/>[encodeDesign.ts]"]
  node_creator_segment_reducers{{"Segment reduce<br/>geometry reducer<br/>[segmentReducers.ts]"}}
  node_creator_carriage["Carriage plan<br/>planner<br/>[carriagePlanner.ts]"]
  node_creator_foot{{"Foot track<br/>state tracker<br/>[foot.ts]"}}
  node_creator_manual["Manual stitches<br/>manual mode<br/>[manualStitch.ts]"]
  node_creator_project_store[("Project store<br/>indexeddb store<br/>[projectStore.ts]")]
  node_creator_binary_export["Binary export<br/>sh7 encoder<br/>[sh7BinaryExport.ts]"]
  node_creator_json_export["JSON export<br/>project wrapper<br/>[sh7Json.ts]"]
  node_creator_binary_import["Binary import<br/>sh7 import<br/>[sh7BinaryImport.ts]"]
end

subgraph group_ui["Browser UI"]
  node_ui_main["Creator app<br/>app shell<br/>[main.ts]"]
  node_ui_editor["Editor<br/>[index.ts]"]
  node_ui_preview["Preview<br/>playback view<br/>[index.ts]"]
  node_ui_store["UI store<br/>state store<br/>[uiStore.ts]"]
  node_ui_sidebar["Sidebar<br/>panel<br/>[index.ts]"]
  node_ui_modals["Modals<br/>dialog set<br/>[DialogBase.ts]"]
  node_ui_gestures{{"Gestures<br/>input layer<br/>[index.ts]"}}
end

subgraph group_shared["Shared geometry"]
  node_shared_satin_shape{{"Satin shape<br/>geometry helper<br/>[satinShape.ts]"}}
end

node_docs_format_md -->|"documents"| node_format_chunk_schema
node_docs_format_ksy -->|"describes"| node_format_record_codec
node_format_chunk_schema -->|"uses"| node_format_record_codec
node_parser_file -->|"parses"| node_parser_header
node_parser_file -->|"parses"| node_parser_chunks
node_parser_chunks -->|"delegates"| node_parser_stitches
node_parser_chunks -->|"delegates"| node_parser_satin
node_parser_file -->|"validates"| node_parser_validate
node_parser_validate -->|"checks"| node_format_chunk_schema
node_parser_satin -->|"uses"| node_shared_satin_shape
node_creator_project -->|"defines"| node_creator_types
node_creator_project -->|"feeds"| node_creator_segment_reducers
node_creator_segment_reducers -->|"feeds"| node_creator_pipeline
node_creator_pipeline -->|"plans"| node_creator_carriage
node_creator_pipeline -->|"tracks"| node_creator_foot
node_creator_pipeline -->|"emits"| node_creator_encode_design
node_creator_manual -->|"writes"| node_creator_project
node_creator_project_store -->|"persists"| node_creator_project
node_creator_binary_import -->|"creates"| node_creator_project
node_creator_binary_export -->|"exports"| node_creator_pipeline
node_creator_json_export -->|"serializes"| node_creator_project
node_ui_main -->|"boots"| node_ui_store
node_ui_main -->|"mounts"| node_ui_editor
node_ui_main -->|"mounts"| node_ui_preview
node_ui_editor -->|"subscribes"| node_ui_store
node_ui_preview -->|"subscribes"| node_ui_store
node_ui_sidebar -->|"reads"| node_ui_store
node_ui_modals -->|"coordinates"| node_ui_store
node_ui_gestures -->|"drives"| node_ui_editor
node_ui_editor -->|"edits"| node_creator_project
node_ui_preview -->|"renders"| node_creator_pipeline

click node_docs_format_md "https://github.com/vortiago/sh7pad/blob/main/FORMAT.md"
click node_docs_format_ksy "https://github.com/vortiago/sh7pad/blob/main/docs/format.ksy"
click node_format_chunk_schema "https://github.com/vortiago/sh7pad/blob/main/src/format/chunkSchema.ts"
click node_format_record_codec "https://github.com/vortiago/sh7pad/blob/main/src/format/recordCodec.ts"
click node_parser_file "https://github.com/vortiago/sh7pad/blob/main/src/parser/parseFile.ts"
click node_parser_header "https://github.com/vortiago/sh7pad/blob/main/src/parser/parseHeader.ts"
click node_parser_chunks "https://github.com/vortiago/sh7pad/blob/main/src/parser/parseChunks.ts"
click node_parser_stitches "https://github.com/vortiago/sh7pad/blob/main/src/parser/parseStitches.ts"
click node_parser_satin "https://github.com/vortiago/sh7pad/blob/main/src/parser/parseSatin.ts"
click node_parser_validate "https://github.com/vortiago/sh7pad/blob/main/src/parser/validateSh7Bytes.ts"
click node_shared_satin_shape "https://github.com/vortiago/sh7pad/blob/main/src/shared/satinShape.ts"
click node_creator_project "https://github.com/vortiago/sh7pad/blob/main/src/creator/project.ts"
click node_creator_types "https://github.com/vortiago/sh7pad/blob/main/src/creator/types.ts"
click node_creator_pipeline "https://github.com/vortiago/sh7pad/blob/main/src/creator/pipeline/stitch.ts"
click node_creator_encode_design "https://github.com/vortiago/sh7pad/blob/main/src/creator/pipeline/encodeDesign.ts"
click node_creator_segment_reducers "https://github.com/vortiago/sh7pad/blob/main/src/creator/segmentReducers.ts"
click node_creator_carriage "https://github.com/vortiago/sh7pad/blob/main/src/creator/carriagePlanner.ts"
click node_creator_foot "https://github.com/vortiago/sh7pad/blob/main/src/creator/foot.ts"
click node_creator_manual "https://github.com/vortiago/sh7pad/blob/main/src/creator/manualStitch.ts"
click node_creator_project_store "https://github.com/vortiago/sh7pad/blob/main/src/creator/projectStore.ts"
click node_creator_binary_export "https://github.com/vortiago/sh7pad/blob/main/src/creator/sh7BinaryExport.ts"
click node_creator_json_export "https://github.com/vortiago/sh7pad/blob/main/src/creator/sh7Json.ts"
click node_creator_binary_import "https://github.com/vortiago/sh7pad/blob/main/src/creator/sh7BinaryImport.ts"
click node_ui_main "https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/main.ts"
click node_ui_editor "https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/editor/index.ts"
click node_ui_preview "https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/preview/index.ts"
click node_ui_store "https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/store/uiStore.ts"
click node_ui_sidebar "https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/sidebar/index.ts"
click node_ui_modals "https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/modals/DialogBase.ts"
click node_ui_gestures "https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/canvasGesture/index.ts"

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_docs_format_md,node_docs_format_ksy toneBlue
class node_format_chunk_schema,node_format_record_codec toneAmber
class node_parser_file,node_parser_header,node_parser_chunks,node_parser_stitches,node_parser_satin,node_parser_validate toneMint
class node_creator_project,node_creator_types,node_creator_pipeline,node_creator_encode_design,node_creator_segment_reducers,node_creator_carriage,node_creator_foot,node_creator_manual,node_creator_project_store,node_creator_binary_export,node_creator_json_export,node_creator_binary_import toneRose
class node_ui_main,node_ui_editor,node_ui_preview,node_ui_store,node_ui_sidebar,node_ui_modals,node_ui_gestures toneIndigo
class node_shared_satin_shape toneTeal
```

## Components

### Docs & research

Reverse-engineered format notes, user guides, and design documentation.

- [FORMAT.md](https://github.com/vortiago/sh7pad/blob/main/FORMAT.md): format reference · Reverse-engineered binary format reference. · `FORMAT.md`
- [Kaitai spec](https://github.com/vortiago/sh7pad/blob/main/docs/format.ksy): format spec · Subset Kaitai Struct description of the .sh7 format. · `docs/format.ksy`

### Format core

Low-level binary chunk and record codecs shared by parsing and encoding.

- [Chunk schema](https://github.com/vortiago/sh7pad/blob/main/src/format/chunkSchema.ts): codec schema · Chunk definitions and structural schema for the binary format. · `src/format/chunkSchema.ts`
- [Record codec](https://github.com/vortiago/sh7pad/blob/main/src/format/recordCodec.ts): binary codec · Encodes and decodes low-level records. · `src/format/recordCodec.ts`

### Import parser

Reads .sh7 bytes, parses structure, and applies layered validation.

- [File parse](https://github.com/vortiago/sh7pad/blob/main/src/parser/parseFile.ts): file parser · Top-level .sh7 file parsing entry point. · `src/parser/parseFile.ts`
- [Header parse](https://github.com/vortiago/sh7pad/blob/main/src/parser/parseHeader.ts): header parser · Parses the file header and version metadata. · `src/parser/parseHeader.ts`
- [Chunk parse](https://github.com/vortiago/sh7pad/blob/main/src/parser/parseChunks.ts): chunk parser · Reads chunk layout and delegates to specialized parsers. · `src/parser/parseChunks.ts`
- [Stitch parse](https://github.com/vortiago/sh7pad/blob/main/src/parser/parseStitches.ts): stitch parser · Parses stitch records from file data. · `src/parser/parseStitches.ts`
- [Satin parse](https://github.com/vortiago/sh7pad/blob/main/src/parser/parseSatin.ts): satin parser · Parses satin-specific payload structures. · `src/parser/parseSatin.ts`
- [Validation](https://github.com/vortiago/sh7pad/blob/main/src/parser/validateSh7Bytes.ts): validation suite · Layered validation for headers, records, chunks, metadata, and version constraints. · `src/parser/validateSh7Bytes.ts`

### Project engine

Project model, geometry intent, stitch generation, persistence, and export.

- [Project model](https://github.com/vortiago/sh7pad/blob/main/src/creator/project.ts): domain model · Central editable project representation for design and manual modes. · `src/creator/project.ts`
- [Project types](https://github.com/vortiago/sh7pad/blob/main/src/creator/types.ts): types · Core project and stitch domain type definitions. · `src/creator/types.ts`
- [Stitch pipeline](https://github.com/vortiago/sh7pad/blob/main/src/creator/pipeline/stitch.ts): generation pipeline · Transforms geometric intent into stitch output. · `src/creator/pipeline/stitch.ts`
- [Encode design](https://github.com/vortiago/sh7pad/blob/main/src/creator/pipeline/encodeDesign.ts): encoder · Final design encoding stage for generated stitch output. · `src/creator/pipeline/encodeDesign.ts`
- [Segment reduce](https://github.com/vortiago/sh7pad/blob/main/src/creator/segmentReducers.ts): geometry reducer · Reduces design segments before stitch generation. · `src/creator/segmentReducers.ts`
- [Carriage plan](https://github.com/vortiago/sh7pad/blob/main/src/creator/carriagePlanner.ts): planner · Plans carriage motion and stitch routing. · `src/creator/carriagePlanner.ts`
- [Foot track](https://github.com/vortiago/sh7pad/blob/main/src/creator/foot.ts): state tracker · Tracks foot state during stitch emission. · `src/creator/foot.ts`
- [Manual stitches](https://github.com/vortiago/sh7pad/blob/main/src/creator/manualStitch.ts): manual mode · Explicit stitch and jump-stitch authoring path. · `src/creator/manualStitch.ts`
- [Project store](https://github.com/vortiago/sh7pad/blob/main/src/creator/projectStore.ts): indexeddb store · Browser-local persistence for saved and recent projects. · `src/creator/projectStore.ts`
- [Binary export](https://github.com/vortiago/sh7pad/blob/main/src/creator/sh7BinaryExport.ts): sh7 encoder · Exports native .sh7 binary files. · `src/creator/sh7BinaryExport.ts`
- [JSON export](https://github.com/vortiago/sh7pad/blob/main/src/creator/sh7Json.ts): project wrapper · Exports .sh7c.json project wrappers. · `src/creator/sh7Json.ts`
- [Binary import](https://github.com/vortiago/sh7pad/blob/main/src/creator/sh7BinaryImport.ts): sh7 import · Converts parsed bytes into project-ready structures. · `src/creator/sh7BinaryImport.ts`

### Browser UI

Interactive creator, preview, panels, gestures, and state management.

- [Creator app](https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/main.ts): app shell · Browser entrypoint and mounting for the creator experience. · `src/ui/creator/main.ts`
- [Editor](https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/editor/index.ts): canvas editor · Interactive design canvas and interaction wiring. · `src/ui/creator/editor/index.ts`
- [Preview](https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/preview/index.ts): playback view · Simulated stitched result and transport playback. · `src/ui/creator/preview/index.ts`
- [UI store](https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/store/uiStore.ts): state store · UI state, render scheduling, layout attributes, and transport state. · `src/ui/creator/store/uiStore.ts`
- [Sidebar](https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/sidebar/index.ts): panel · Project settings, stitch settings, and preview options. · `src/ui/creator/sidebar/index.ts`
- [Modals](https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/modals/DialogBase.ts): dialog set · Export, new project, and disclaimer dialogs. · `src/ui/creator/modals/DialogBase.ts`
- [Gestures](https://github.com/vortiago/sh7pad/blob/main/src/ui/creator/canvasGesture/index.ts): input layer · Pointer, touch, and camera gesture handling. · `src/ui/creator/canvasGesture/index.ts`

### Shared geometry

Geometry helpers used by parser and creator logic.

- [Satin shape](https://github.com/vortiago/sh7pad/blob/main/src/shared/satinShape.ts): geometry helper · Shared satin geometry helpers used by generation and validation. · `src/shared/satinShape.ts`

## Connections

- FORMAT.md → Chunk schema: documents · Format notes describe the binary chunk model.
- Kaitai spec → Record codec: describes · Kaitai subset mirrors record encoding rules.
- Chunk schema → Record codec: uses · Chunk structure is built on record codecs.
- File parse → Header parse: parses · File parse begins with header extraction.
- File parse → Chunk parse: parses · Then reads chunk structure and payloads.
- Chunk parse → Stitch parse: delegates · Chunk parsing routes stitch content to the stitch parser.
- Chunk parse → Satin parse: delegates · Chunk parsing routes satin payloads to the satin parser.
- File parse → Validation: validates · Parsed bytes are checked against layered constraints.
- Validation → Chunk schema: checks · Validation enforces format structure and record rules.
- Satin parse → Satin shape: uses · Satin parsing shares satin geometry definitions.
- Project model → Project types: defines · Project model is built from shared domain types.
- Project model → Segment reduce: feeds · Project geometry is reduced before stitch generation.
- Segment reduce → Stitch pipeline: feeds · Reduced segments enter the stitch pipeline.
- Stitch pipeline → Carriage plan: plans · Pipeline determines carriage motion.
- Stitch pipeline → Foot track: tracks · Pipeline maintains foot state during emission.
- Stitch pipeline → Encode design: emits · Pipeline ends in encoded design output.
- Manual stitches → Project model: writes · Manual mode stores explicit stitch intent in the project.
- Project store → Project model: persists · Project state is stored locally in IndexedDB.
- Binary import → Project model: creates · Imported .sh7 data becomes an editable project.
- Binary export → Stitch pipeline: exports · Binary export serializes generated design output.
- JSON export → Project model: serializes · JSON export wraps the editable project model.
- Creator app → UI store: boots · App shell initializes UI state and rendering.
- Creator app → Editor: mounts · Creator shell mounts the editor canvas.
- Creator app → Preview: mounts · Creator shell mounts preview playback.
- Editor → UI store: subscribes · Editor renders from store-driven state.
- Preview → UI store: subscribes · Preview and transport reflect store state.
- Sidebar → UI store: reads · Sidebar panels are driven from shared UI state.
- Modals → UI store: coordinates · Dialogs update or reflect application state.
- Gestures → Editor: drives · Pointer and touch gestures manipulate the editor.
- Editor → Project model: edits · Canvas interactions mutate project intent.
- Preview → Stitch pipeline: renders · Preview consumes generated stitch output.
