XCode-Claude-Workflow/ARCHITECTURE.md

ARCHITECTURE.md — SoliCards

Overview

SoliCards is a native SwiftUI solitaire app supporting three game variants (Klondike, Spider, FreeCell) across iOS, iPadOS, and macOS from a single codebase. It was ported from a 2,843-line vanilla JavaScript web app to native Swift.

Pattern: MVVM + Protocol-Oriented Strategy

Why MVVM

SwiftUI's @Observable macro (iOS 17+) gives property-level observation — a score change does not re-render the tableau. This is critical for a card game with many rapidly-changing UI elements during drag operations.

Why Strategy Pattern for Variants

The three variants share concepts (cards, foundations, tableaus, undo, scoring) but have radically different rules. A single GameRules protocol defines the contract:

GameRules (protocol)
├── KlondikeRules    — alternating colors, draw 1/3, foundation A→K
├── SpiderRules      — same-suit sequences, 2-deck, auto-complete K→A
└── FreeCellRules    — power moves: (1+freecells) × 2^emptyTableaus

Adding a new variant means implementing one struct + one board view. Zero changes to existing code.

Why Not TCA

The game has no networking, no side effects beyond sound and persistence, and all state mutations are synchronous UI gestures. TCA's unidirectional architecture would add overhead without benefit.

Key Architectural Decisions

1. DragGesture, not onDrag/onDrop

SwiftUI's onDrag/onDrop uses the Transferable protocol, which serializes data through the system pasteboard. This is designed for inter-app drag and drop. For internal card movement:

• DragGesture gives direct control over positioning and animation
• DropTargetPreferenceKey reports frame geometry for hit-testing
• DraggedCardsOverlay renders floating cards in the board's coordinate space
• No serialization overhead

2. @Observable, not ObservableObject

The @Observable macro (Observation framework) was chosen over ObservableObject/@Published because:

• Property-level observation — only views reading a changed property re-render
• No @Published boilerplate
• Works with @Bindable for two-way bindings
• Cleaner nested observable objects

3. @MainActor on ViewModels, not actors for game logic

All game state mutations are triggered by user gestures on the main thread. Using an actor would force every game action to be async, adding await noise for no concurrency benefit. Only SoundManager uses async for off-main-thread audio loading.

4. Value-type GameSnapshot for undo

Undo is implemented via an array of GameSnapshot structs (Codable value types). Each snapshot is a deep copy of all card arrays, score, and moves. This avoids reference-type aliasing bugs that would occur with class-based state. The history caps at 20 entries.

5. PNG images from asset catalog, not Canvas drawing

The source project already had 52 card front PNGs in multiple styles. Re-drawing cards procedurally would be wasted effort. Asset catalog images are:

• Memory-mapped by the system (efficient loading)
• Automatically thinned for App Store builds
• Validated at compile time

6. Debounced auto-save

Game state is saved via SwiftData after 2 seconds of inactivity (not on every move). This prevents excessive disk writes during rapid play. Immediate save occurs on app background and pause.

7. trailingSuffix(while:) extension

Swift's standard library does not include suffix(while:) on BidirectionalCollection. Rather than adding a dependency (Swift Algorithms), a small trailingSuffix(while:) extension on Array provides the same functionality for finding face-up card runs.

Data Flow

User Gesture (tap / drag)
    │
    ▼
CardStackView / CardView
    │  DragGesture / onTapGesture
    ▼
GameViewModel
    │  rules.canMove() → validation
    │  state.pushHistory() → undo stack
    │  state mutation → @Observable triggers SwiftUI diff
    │  soundManager.play() → audio feedback
    │  rules.isWon() → phase transition
    │  scheduleAutoSave() → debounced SwiftData write
    ▼
GameBoardView re-renders only changed cards

Persistence Model

Three SwiftData @Model types:

Model	Purpose	Lifecycle
GameRecord	Saved game state (JSON-encoded GameSnapshot)	One per variant, deleted on win
StatsRecord	Win/loss/streak per variant+difficulty	Permanent, updated on win/loss
PrefsRecord	Theme, card style, sound toggle	Singleton, updated on change

File Organization

Files are organized by architectural layer, not by feature:

• Models/ — pure data types, no dependencies
• GameEngine/ — game logic, depends only on Models
• ViewModels/ — UI state management, depends on GameEngine + Services
• Views/ — SwiftUI views, depends on ViewModels
• Services/ — sound, haptics, timer (side effects)
• Persistence/ — SwiftData models + manager
• Theme/ — color definitions and theme state

This layering ensures that GameEngine can be tested without any UI or persistence dependencies.