CutList/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

CutList is a Windows Forms 1D bin packing optimization application that helps users optimize material cutting. It calculates efficient bin packing solutions to minimize waste when cutting stock materials into required parts.

Framework: .NET 8.0 (Windows Forms) Key Dependencies: Math-Expression-Evaluator (input parsing), Newtonsoft.Json (serialization)

Build Commands

# Build entire solution
dotnet build CutList.sln

# Build specific project
dotnet build CutList/CutList.csproj
dotnet build CutList.Core/CutList.Core.csproj

# Run the application
dotnet run --project CutList/CutList.csproj

# Clean build
dotnet clean CutList.sln

Architecture

Project Structure

• CutList/ - Main Windows Forms application (UI layer)
• CutList.Core/ - Core library with domain models and packing algorithms (shareable, platform-agnostic)

Key Patterns

MVP (Model-View-Presenter)

• MainForm implements IMainView (pure UI, no business logic)
• MainFormPresenter orchestrates all business logic
• Document contains application state

Result Pattern

• Result<T> in Common/Result.cs for standardized error handling
• Use Result<T>.Success(value) and Result<T>.Failure(error) instead of exceptions for expected errors

Factory Pattern

• IEngineFactory creates packing engines
• Allows swapping algorithm implementations

Data Flow

1. User enters parts/bins in MainForm
2. MainFormPresenter calls CutListService.Pack()
3. CutListService converts input models to core models (MultiBin, BinItem)
4. MultiBinEngine coordinates packing across bin types
5. AdvancedFitEngine performs 1D bin packing (first-fit decreasing with optimization)
6. Results displayed in ResultsForm

Key Services

• CutListService: Bridges UI models to core packing algorithms
• DocumentService: JSON file persistence

Domain Models (CutList.Core)

• BinItem: Item to be packed (with label, length)
• MultiBin: Stock bin type with length, quantity (-1 = unlimited), priority
• Bin: Packed bin containing items
• Tool: Cutting tool with kerf/blade width

Unit Handling

• ArchUnits: Converts feet/inches/fractions to decimals (accepts "12'", "6"", "12 1/2"", etc.)
• FormatHelper: Converts decimals to mixed fractions for display
• Internal calculations use inches; format on display

Important Conventions

• Nullable reference types enabled - handle nulls explicitly
• Collections are encapsulated - use AsReadOnly(), access via Add* methods
• Validation in domain models - constructors and properties validate inputs
• Parameterless constructors on Tool/MultiBin are for JSON serialization only
• Spacing property on engines handles blade/kerf width
• Priority system: Lower priority bins are used first

Key Files

File	Purpose
Presenters/MainFormPresenter.cs	Main business logic orchestrator
Services/CutListService.cs	Packing algorithm interface
CutList.Core/Nesting/AdvancedFitEngine.cs	Core packing algorithm
CutList.Core/Nesting/MultiBinEngine.cs	Multi-bin orchestration
CutList.Core/ArchUnits.cs	Unit conversion
CutList.Core/FormatHelper.cs	Output formatting