Skip to content

chore: stale docs #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
0x7067 merged 2 commits into from
Jan 8, 2026
Merged

chore: stale docs #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7e724f2
chore: stale docs
0x7067 Jan 8, 2026
a8f0a1d
feat: new CLAUDE.md
0x7067 Jan 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
247 changes: 60 additions & 187 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,213 +4,86 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

## Project Overview

ConwayGame is a production-ready iOS implementation of Conway's Game of Life built with SwiftUI and Core Data. The architecture follows clean separation of concerns with distinct layers for game logic, persistence, and UI.
Conway's Game of Life implementation with three components:
- **ConwayGame/** - iOS SwiftUI app with Core Data persistence
- **ConwayGameEngine/** - Reusable Swift Package with pure game logic and CLI
- **ConwayAPI/** - Vapor REST API exposing engine functionality

## Documentation Structure

This project maintains several documentation files with distinct purposes:

- **CLAUDE.md** (this file): Guidance for Claude Code AI assistant when working with the codebase
- **CONTRIBUTING.md**: Comprehensive contributor guide for human developers (setup, architecture, workflow)
- **README.md**: Project overview and quick start instructions for end users
- **Swift API Documentation**: Comprehensive documentation comments throughout all public APIs following Apple's Swift documentation guidelines
- **GitHub Templates** (`.github/`): Structured templates for issues and pull requests
- Bug reports, feature requests, performance issues, documentation, and questions
- Pull request template with architecture impact assessment and testing checklists

## Build and Test Commands
## Build & Test Commands

```bash
# Build the project
xcodebuild -scheme ConwayGame -configuration Debug build

# Run all tests
# iOS app tests (all)
xcodebuild -scheme ConwayGame -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test

# Run specific test target
xcodebuild -scheme ConwayGameTests -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test

# Run specific test file (example)
# iOS specific test class
xcodebuild -scheme ConwayGame -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test -only-testing:ConwayGameTests/GameEngineTests

# Run specific test method (example)
# iOS specific test method
xcodebuild -scheme ConwayGame -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test -only-testing:ConwayGameTests/GameEngineTests/testBasicPatterns

# Build for release
xcodebuild -scheme ConwayGame -configuration Release build
# Engine package tests
cd ConwayGameEngine && swift test

# API tests
cd ConwayAPI && swift test

# Clean build folder
xcodebuild -scheme ConwayGame clean
# Run CLI
cd ConwayGameEngine && swift run conway-cli pattern glider
cd ConwayGameEngine && swift run conway-cli run 10 10 20 random --density=0.3 --rules=highlife

# Swift Package commands
cd ConwayGameEngine
# Run API server
cd ConwayAPI && swift run conway-api

# Build Swift Package
swift build
# Format code (run before committing)
swiftformat ConwayGameEngine ConwayAPI

# Run Swift Package tests
swift test
# Check formatting
swiftformat ConwayGameEngine ConwayAPI --lint
```

# Run CLI tool
swift run conway-cli --help
swift run conway-cli pattern glider
## Architecture

# Code Formatting Commands
```
┌─────────────────────────┐
│ iOS App (SwiftUI) │ Views → ViewModels
├─────────────────────────┤
│ Service Layer │ GameService
├─────────────────────────┤
│ Repository Layer │ CoreDataBoardRepository
├─────────────────────────┤
│ ConwayGameEngine │ Pure game logic, no dependencies
└─────────────────────────┘
```

# Install SwiftFormat (if not already installed)
brew install swiftformat
**Key patterns:**
- Protocol-oriented design for all major components (testability)
- MVVM with `@MainActor` ViewModels
- Repository pattern abstracting Core Data
- Dependency injection via FactoryKit (`FactoryContainer.swift`)
- Centralized configuration (`GameEngineConfiguration`) eliminates magic numbers

# Format all Swift code in ConwayGameEngine
cd ConwayGameEngine && swiftformat .
**Naming conventions:**
- Protocols describe behavior: `GameEngine`, `GameService`, `BoardRepository`
- Implementations prefixed: `ConwayGameEngine`, `DefaultGameService`, `CoreDataBoardRepository`

# Check formatting without making changes (ConwayGameEngine)
cd ConwayGameEngine && swiftformat --lint .
## Code Style

# Format all Swift code in ConwayAPI
cd ConwayAPI && swiftformat .
SwiftFormat enforced in CI:
- Swift 5.9+, compatible with Swift 6 language mode
- 4-space indentation, 120-char line length
- No redundant `self`, alphabetized imports
- Use `struct` over `class` when possible
- Use `@inline(__always)` only for proven hot paths

# Check formatting without making changes (ConwayAPI)
cd ConwayAPI && swiftformat --lint .
## Error Handling

# Format entire project (run from project root)
swiftformat ConwayGameEngine ConwayAPI
- `GameError` enum for core operations
- `UserFriendlyError` protocol for UI-facing errors with recovery actions
- Context-aware wrapping via `ConwayGameUserError`

# Check entire project formatting (run from project root)
swiftformat ConwayGameEngine ConwayAPI --lint
```
## Testing

## Architecture Overview

The codebase follows a layered architecture designed for future extensibility and platform independence:

### Core Layers

1. **Configuration System** (`ConwayGameEngine/Sources/ConwayGameEngine/`)
- `GameEngineConfiguration`: Configurable Conway rules and simulation parameters
- `PlaySpeedConfiguration`: Animation timing configuration for iOS and CLI
- Supports multiple rule variants (Conway, HighLife, Day and Night)
- Eliminates magic numbers and ensures cross-platform consistency

2. **Pure Game Logic Layer** (`Services/GameEngine.swift`)
- `GameEngine` protocol: Core Conway's Game of Life computation
- `ConwayGameEngine`: Optimized implementation with configurable rules and early termination
- `GameRules`: Static methods for cell survival/birth logic using configurable neighbor counts

3. **Data Layer** (`Models/`)
- `Board`: Main entity with validation, state history for convergence detection
- `GameState`: Represents computed state at specific generation
- `GameError`: Comprehensive error handling enumeration
- `ConvergenceType`: Tracks game state evolution (continuing/extinct/cyclical)

4. **Service Layer** (`Services/GameService.swift`)
- `GameService` protocol: Business logic orchestration
- `DefaultGameService`: Coordinates game engine, persistence, and convergence detection
- Async/await patterns for all operations

5. **Repository Pattern** (`Repository/`)
- `BoardRepository` protocol: Persistence abstraction
- `CoreDataBoardRepository`: Core Data implementation
- Complete CRUD operations for boards

6. **Dependency Injection** (`Utils/FactoryContainer.swift`)
- FactoryKit-based container managing all service dependencies and configurations
- Ensures consistent object graph and configuration throughout app

7. **Error Handling & User Experience** (`Utils/`)
- `UserFriendlyError.swift`: Protocol-based system for transforming technical errors into user-friendly messages
- `ErrorAlertModifier.swift`: SwiftUI integration with contextual recovery actions and smart error alerts
- Context-aware recovery actions (.boardLoading, .gameSimulation, .dataPersistence)
- Comprehensive error transformation covering all Conway Game scenarios

### Key Design Patterns

- **Protocol-oriented design**: All major components are protocol-based for testability
- **Repository pattern**: Abstracts persistence layer
- **MVVM**: ViewModels coordinate between UI and services
- **Configuration management**: Centralized configuration system eliminates magic numbers
- **Dependency injection**: FactoryKit-based dependency injection ensures consistent configurations across iOS and CLI
- **Convergence detection**: Uses state hashing and history tracking for cycle/stability detection
- **User-friendly error handling**: Context-aware error transformation with actionable recovery options

## Testing Structure

- `GameEngineTests.swift`: Core Conway's Game logic, edge cases, patterns
- `GameServiceTests.swift`: Service layer integration tests
- `ConvergenceDetectorTests.swift`: Convergence detection algorithms
- `BoardRepositoryTests.swift`: Persistence layer tests
- `ViewModelTests.swift`: UI logic tests and error handling integration
- `UserFriendlyErrorTests.swift`: Error transformation, recovery actions, and context-aware behavior
- `PaginationViewModelTests.swift`: Pagination behavior and sorting tests
- `PerformanceBenchmarkTests.swift`: Core Data scaling and performance tests
- `SyntheticDataGenerator.swift`: Test data generation utility for performance testing

## Performance Considerations

- **Memory optimization**: Uses `@inline(__always)` for hot paths in game logic
- **Identity checking**: Game engine returns same instance when no changes occur
- **Early termination**: Computation stops when stable states are detected
- **Background processing**: Long computations run on background queues
- **State hashing**: Efficient bit-packed base64 encoding for cycle detection
- **Core Data pagination**: Efficient pagination with configurable page sizes to handle large datasets
- **Performance testing**: Comprehensive benchmark suite for Core Data scaling with `SyntheticDataGenerator`

## Core Data Integration

- Uses `PersistenceController.shared` for Core Data stack
- Boards persist across app launches with full state history
- Environment injection via `.managedObjectContext` in SwiftUI

## Key Files for Extension

- `GameEngineConfiguration.swift`: Add new rule variants or simulation parameters
- `PlaySpeedConfiguration.swift`: Modify timing configurations for iOS and CLI
- `GameEngine.swift`: Modify game computation algorithms or add optimizations
- `GameService.swift`: Add new game operations or API endpoints
- `Board.swift`: Extend data model (ensure validation updates)
- `BoardSortOption.swift`: Add new sorting options for board lists and pagination
- `BoardRepository.swift`: Add new repository methods for data access patterns
- `CoreDataBoardRepository.swift`: Implement new Core Data queries and pagination logic
- `BoardListViewModel.swift`: Extend pagination and filtering capabilities
- `FactoryContainer.swift`: Register new dependencies and configurations
- `ThemeManager.swift`: UI theming and appearance management
- `UserFriendlyError.swift`: Extend error transformation system for new error types or contexts
- `ErrorAlertModifier.swift`: Enhanced error presentation with contextual recovery actions
- `LRUCache.swift`: Performance optimization for caching
- `DesignTokens.swift`: UI design system constants
- `ConvergenceDetector.swift`: Enhance convergence detection algorithms
- `SyntheticDataGenerator.swift`: Extend test data generation for performance testing

### Documentation Files
- `CONTRIBUTING.md`: Update when architecture changes or new development processes are added
- `.github/ISSUE_TEMPLATE/`: Update templates when new components are added or issue categories change
- `.github/pull_request_template.md`: Update when new architecture layers or testing requirements are introduced

## Development Notes

- Game logic is completely UI-independent for future platform portability
- All async operations use structured concurrency
- User-friendly error handling with contextual recovery actions transforms technical errors into actionable guidance
- State validation occurs at model level with throwing initializers
- Logging uses OSLog framework with categorized loggers
- Configuration system eliminates magic numbers and ensures consistency across platforms
- Multiple rule variants supported: Conway (default), HighLife, Day and Night
- CLI supports runtime configuration overrides via command-line options
- **API Documentation**: All public APIs include comprehensive Swift documentation comments with usage examples, parameter descriptions, and performance notes following Apple's Swift API Design Guidelines

### Documentation Maintenance

When making changes to the codebase, consider updating documentation:

- **Architecture changes**: Update both CLAUDE.md and CONTRIBUTING.md to reflect new layers, patterns, or components
- **New features**: Update GitHub issue templates if new feature categories are introduced
- **Testing changes**: Update pull request template checklist and CONTRIBUTING.md testing sections
- **Build process changes**: Update build commands in both CLAUDE.md and CONTRIBUTING.md
- **New dependencies**: Update setup instructions in CONTRIBUTING.md
- **API changes**: Update Swift documentation comments when modifying public APIs, including:
- Parameter and return value descriptions
- Usage examples for complex methods
- Performance notes and complexity information
- Error conditions and handling guidance
- Maintain consistency with Apple's Swift API Design Guidelines

Refer contributors to CONTRIBUTING.md for comprehensive setup and development workflow guidance.
- >90% coverage target for core logic
- Integration tests in `EndToEndWorkflowTests.swift`, `CoreDataIntegrationTests.swift`
- `SyntheticDataGenerator.swift` for large dataset testing
- API tests use `XCTVapor` async helpers
Loading
Loading