97 lines
3.3 KiB
Markdown
97 lines
3.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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 |
|