1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
# 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
|
