# dengyu123456/crochet-engine architecture

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

- Interactive diagram: https://gitdiagram.com/dengyu123456/crochet-engine
- Repository: https://github.com/dengyu123456/crochet-engine

## Overview

#### Purpose and delivery surfaces

`crochet_chart_engine` deterministically converts photos or ASCII crochet designs into grid-chart PNGs plus exact per-color stitch metadata. It is distributed as a Python API, command-line tool, and stdio MCP server for agent clients. Primary surfaces are `src/crochet_chart_engine/__init__.py`, `src/crochet_chart_engine/cli.py`, and `src/crochet_chart_engine/mcp_server.py`.

#### Core chart-generation pipeline

The main orchestration lives in `src/crochet_chart_engine/engine.py`. It accepts a Pillow image and chart parameters, validates/selects a crochet technique, derives output grid dimensions, resizes the source, quantizes pixels to a bounded palette, cleans isolated/confetti colors, then produces chart PNG bytes and metadata. The output contract includes grid dimensions, technique, color hex values, exact counts, total stitches, and warnings.

#### Technique-aware geometry boundary

Technique presets are architecture-defining because they change grid interpretation and sizing. `src/crochet_chart_engine/engine.py` applies technique rules for graph, C2C, tapestry, mosaic, and filet. In particular, C2C uses block aspect correction so physical worked dimensions preserve the source image’s apparent proportions rather than treating cells as square.

#### Design-file ingestion and rendering

`src/crochet_chart_engine/design.py` parses the repository’s ASCII design format: palette declarations, optional title/technique metadata, separator, and character-grid rows. It pads irregular rows and maps symbols to palette colors before rendering through the chart machinery. Example source assets are `designs/frog.txt` and `designs/dragon.txt`; `render_design` is exposed through `src/crochet_chart_engine/__init__.py`.

#### Stitch accounting and yarn estimation

Color counts are derived from the finalized grid, making them an output invariant: per-color counts sum to total grid stitches. `src/crochet_chart_engine/yarn.py` consumes chart metadata rather than source images and estimates total and per-color yardage across supported yarn weights. This separates visual/grid generation from material planning.

#### User-facing adapters

The CLI in `src/crochet_chart_engine/cli.py` exposes distinct chart, design, and yarn workflows around the library API. The MCP adapter in `src/crochet_chart_engine/mcp_server.py` presents equivalent capabilities as agent tools over stdio: photo conversion, ASCII design rendering, and yarn estimation. It handles transport-facing concerns such as local paths, base64/saved PNG output, and JSON-safe metadata rather than changing engine behavior.

#### Runtime and dependencies

The runtime is Python with Pillow and NumPy as the core image-processing dependencies, declared in `pyproject.toml`. Background removal is optional via the `rembg` extra, so it is an enrichment boundary rather than a required pipeline stage. MCP support is optional and launched as `python -m crochet_chart_engine.mcp_server`; `server.json` likely provides server/package integration metadata.

#### Validation focus

`tests/test_engine.py` is the visible behavioral verification point for deterministic engine outcomes. Determinism is central: repeated inputs and parameters must yield the same grid, rendered chart, color palette, and stitch totals.

Main entry points: [`src/crochet_chart_engine/engine.py`](https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/engine.py) (Chart orchestrator), [`src/crochet_chart_engine/design.py`](https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/design.py) (Design renderer), [`src/crochet_chart_engine/mcp_server.py`](https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/mcp_server.py) (MCP server), [`src/crochet_chart_engine/cli.py`](https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_adapters["Delivery adapters"]
  node_api["Python API<br/>package surface<br/>[__init__.py]"]
  node_cli["CLI<br/>command adapter<br/>[cli.py]"]
  node_mcp["MCP server<br/>stdio adapter<br/>[mcp_server.py]"]
  node_server_metadata["Server integration metadata<br/>[server.json]"]
end

subgraph group_chart["Chart generation"]
  node_engine["Chart orchestrator<br/>pipeline<br/>[engine.py]"]
  node_techniques{{"Technique geometry<br/>rule set<br/>[engine.py]"}}
  node_image_grid["Image-to-grid processing<br/>image pipeline<br/>[engine.py]"]
  node_chart_output["Chart PNG and metadata<br/>output contract<br/>[engine.py]"]
  node_pillow_numpy["Pillow and NumPy<br/>image dependencies<br/>[pyproject.toml]"]
  node_rembg["Optional background removal<br/>optional enrichment<br/>[pyproject.toml]"]
end

subgraph group_design["Design rendering"]
  node_design_parser["ASCII design parser<br/>design ingestion<br/>[design.py]"]
  node_design_renderer["Design renderer<br/>grid renderer<br/>[design.py]"]
  node_frog_design["Frog design<br/>example asset<br/>[frog.txt]"]
  node_dragon_design["Dragon design<br/>example asset<br/>[dragon.txt]"]
end

subgraph group_planning["Material planning"]
  node_yarn["Yarn estimator<br/>material planner<br/>[yarn.py]"]
end

node_api -->|"chart API"| node_engine
node_api -->|"render_design"| node_design_renderer
node_cli -->|"chart workflow"| node_engine
node_cli -->|"design workflow"| node_design_renderer
node_cli -->|"yarn workflow"| node_yarn
node_mcp -->|"photo tool"| node_engine
node_mcp -->|"design tool"| node_design_renderer
node_mcp -->|"yarn tool"| node_yarn
node_server_metadata -.->|"integration"| node_mcp
node_engine -->|"selects and applies"| node_techniques
node_engine -->|"processes source image"| node_image_grid
node_techniques -->|"sets grid dimensions"| node_image_grid
node_image_grid -->|"renders finalized grid"| node_chart_output
node_pillow_numpy -->|"implements processing"| node_image_grid
node_rembg -.->|"optional preprocessing"| node_image_grid
node_design_parser -->|"palette and grid"| node_design_renderer
node_design_renderer -->|"renders chart"| node_chart_output
node_frog_design -->|"input"| node_design_parser
node_dragon_design -->|"input"| node_design_parser
node_chart_output -->|"finalized metadata"| node_yarn

click node_api "https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/__init__.py"
click node_cli "https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/cli.py"
click node_mcp "https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/mcp_server.py"
click node_engine "https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/engine.py"
click node_techniques "https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/engine.py"
click node_image_grid "https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/engine.py"
click node_chart_output "https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/engine.py"
click node_pillow_numpy "https://github.com/dengyu123456/crochet-engine/blob/main/pyproject.toml"
click node_rembg "https://github.com/dengyu123456/crochet-engine/blob/main/pyproject.toml"
click node_design_parser "https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/design.py"
click node_design_renderer "https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/design.py"
click node_frog_design "https://github.com/dengyu123456/crochet-engine/blob/main/designs/frog.txt"
click node_dragon_design "https://github.com/dengyu123456/crochet-engine/blob/main/designs/dragon.txt"
click node_yarn "https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/yarn.py"
click node_server_metadata "https://github.com/dengyu123456/crochet-engine/blob/main/server.json"

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_api,node_cli,node_mcp,node_server_metadata toneBlue
class node_engine,node_techniques,node_image_grid,node_chart_output,node_pillow_numpy,node_rembg toneAmber
class node_design_parser,node_design_renderer,node_frog_design,node_dragon_design toneMint
class node_yarn toneRose
```

## Components

### Delivery adapters

- [Python API](https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/__init__.py): package surface · Exports chart and design rendering APIs. · `src/crochet_chart_engine/__init__.py`
- [CLI](https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/cli.py): command adapter · Provides chart, design, and yarn workflows. · `src/crochet_chart_engine/cli.py`
- [MCP server](https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/mcp_server.py): stdio adapter · Exposes equivalent capabilities as agent tools. · `src/crochet_chart_engine/mcp_server.py`
- [Server integration metadata](https://github.com/dengyu123456/crochet-engine/blob/main/server.json): integration metadata · `server.json`

### Chart generation

- [Chart orchestrator](https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/engine.py): pipeline · Validates parameters and coordinates deterministic chart creation. · `src/crochet_chart_engine/engine.py`
- [Technique geometry](https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/engine.py): rule set · Applies graph, C2C, tapestry, mosaic, and filet sizing rules. · `src/crochet_chart_engine/engine.py`
- [Image-to-grid processing](https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/engine.py): image pipeline · Resizes, quantizes, and cleans the bounded color grid. · `src/crochet_chart_engine/engine.py`
- [Chart PNG and metadata](https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/engine.py): output contract · Contains rendered PNG, palette, exact counts, totals, and warnings. · `src/crochet_chart_engine/engine.py`
- [Pillow and NumPy](https://github.com/dengyu123456/crochet-engine/blob/main/pyproject.toml): image dependencies · Required image-processing runtime dependencies. · `pyproject.toml`
- [Optional background removal](https://github.com/dengyu123456/crochet-engine/blob/main/pyproject.toml): optional enrichment · Available through the rembg extra. · `pyproject.toml`

### Design rendering

- [ASCII design parser](https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/design.py): design ingestion · Parses metadata, palette declarations, and irregular symbol grids. · `src/crochet_chart_engine/design.py`
- [Design renderer](https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/design.py): grid renderer · Maps symbols to colors and renders through chart machinery. · `src/crochet_chart_engine/design.py`
- [Frog design](https://github.com/dengyu123456/crochet-engine/blob/main/designs/frog.txt): example asset · `designs/frog.txt`
- [Dragon design](https://github.com/dengyu123456/crochet-engine/blob/main/designs/dragon.txt): example asset · `designs/dragon.txt`

### Material planning

- [Yarn estimator](https://github.com/dengyu123456/crochet-engine/blob/main/src/crochet_chart_engine/yarn.py): material planner · Estimates total and per-color yardage by yarn weight. · `src/crochet_chart_engine/yarn.py`

## Connections

- Python API → Chart orchestrator: chart API
- Python API → Design renderer: render_design
- CLI → Chart orchestrator: chart workflow
- CLI → Design renderer: design workflow
- CLI → Yarn estimator: yarn workflow
- MCP server → Chart orchestrator: photo tool
- MCP server → Design renderer: design tool
- MCP server → Yarn estimator: yarn tool
- Server integration metadata → MCP server: integration
- Chart orchestrator → Technique geometry: selects and applies
- Chart orchestrator → Image-to-grid processing: processes source image
- Technique geometry → Image-to-grid processing: sets grid dimensions
- Image-to-grid processing → Chart PNG and metadata: renders finalized grid
- Pillow and NumPy → Image-to-grid processing: implements processing
- Optional background removal → Image-to-grid processing: optional preprocessing
- ASCII design parser → Design renderer: palette and grid
- Design renderer → Chart PNG and metadata: renders chart
- Frog design → ASCII design parser: input
- Dragon design → ASCII design parser: input
- Chart PNG and metadata → Yarn estimator: finalized metadata