# CLAUDE.md

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

## Common Commands

### Development
- **Build**: `make build` or open the project in Xcode and press the run button
- **Format code**: `make format`
- **Lint code**: `make lint`
- **Run tests**: `make test` or use Xcode's test navigator or ⌘+U

### Distribution
- **Create full distribution**: `make distribute`
- **Archive for distribution**: `make archive`
- **Package app**: `make package`

## Architecture Overview

### Core Structure
This is a SwiftUI-based macOS application for creating Wardley Maps using a text-based domain-specific language.

**Key Components:**
- **MapDocument**: Document-based app architecture using SwiftUI's `FileDocument` protocol
- **MapParser**: Text-to-diagram parsing engine with strategy pattern
- **MapEditor**: Main editing interface with split view (text editor + visual map)
- **MapRenderView**: SwiftUI view that renders the visual map

### Data Flow
1. User types text in `MapTextEditor`
2. `MapParser` parses text using parser strategies
3. Parsed data creates `ParsedMap` with vertices, edges, notes, etc.
4. `MapRenderView` renders the visual representation
5. Changes are automatically saved via document architecture

### Parser Architecture
The parser uses a strategy pattern with these components:
- `MapParserStrategy` protocol for parsing different element types
- Individual strategies: `VertexParserStrategy`, `EdgeParserStrategy`, `NoteParserStrategy`, etc.
- `MapBuilder` accumulates parsed elements into final `ParsedMap`

### Key Data Models
- **Vertex**: Map nodes with position and label
- **MapEdge**: Connections between vertices (with/without arrowheads)
- **Note**: Text annotations at specific positions
- **Blocker**: Obstacles placed in front of vertices
- **Opportunity**: Evolution arrows showing movement
- **Stage**: Different evolution frameworks (general, practice, data, etc.)

### UI Architecture
- **MapEditor**: Main container with adaptive layout (horizontal/vertical split)
- **MapTextEditor**: Text editing with syntax highlighting and search
- **MapRenderView**: Visual map rendering with zoom and pan
- **EvolutionPicker**: Dropdown for selecting evolution framework
- **SearchBar**: Text search functionality with highlight navigation

## Map Language Reference

The app uses a domain-specific language for creating Wardley Maps:

### Basic Elements
- **Nodes**: `Name (x,y)` where x,y are 0-100 coordinates
- **Edges**: `Node -- Node` (line) or `Node -> Node` (arrow)
- **Blockers**: `[Blocker] Node`
- **Evolution**: `[Evolution] Node +/-x`
- **Notes**: `[Note] (x,y) Text`
- **Groups**: `[Group] NodeA, NodeB, NodeC`
- **Axes**: `[I] x`, `[II] x`, `[III] x` for custom stage boundaries

### File Format
- Files use `.wmap` extension with UTI `systems.tranquil.map.wmap`
- Plain text format parsed line by line
- Each line can contain one map element

## Development Notes

### Testing
- Unit tests are in `MapTests/MapTests.swift`
- UI tests are in `MapUITests/`
- Run tests with ⌘+U in Xcode

### Auto-Updates
- Uses Sparkle framework for automatic updates
- Configuration in `Info.plist` and update commands

### Code Style
- Uses swift-format for consistent formatting
- Run `make format` before committing
- All Swift files include GPL license header

### Tool Preferences
- **Use `rg` instead of `grep`** for text searching (ripgrep is faster and more user-friendly)
- **Use `fd` instead of `find`** for file searching (fd is faster and has better defaults)

### Key Dependencies
- SwiftUI for UI framework
- Sparkle for auto-updates
- CoreGraphics for rendering calculations