# System Patterns

## Core Architecture

### Screen Capture System
- Uses ScreenCaptureKit for efficient screen capture
- Implements SCStreamOutput protocol for frame processing
- Handles capture session lifecycle and cleanup
- Manages permissions and error handling

### Board Detection System
Two implemented approaches:

1. Pattern Recognition Approach (Primary)
   - Rectangle detection with Vision framework
   - Aspect ratio-based filtering (0.3-0.5 for taller rectangles)
   - Size-based filtering (0.4 minimum for larger areas)
   - Single observation for precision
   - Board extraction from upper portion
   - Width-based square calculation

2. Coordinate Detection (Fallback)
   - Text recognition for board coordinates
   - Rectangle detection with Vision framework
   - Grid-based validation
   - Coordinate-based refinement

3. Common Infrastructure
   - Asynchronous frame processing
   - Dedicated processing queue
   - Efficient memory management
   - Performance monitoring

### Coordinate Systems
- Vision framework: Bottom-left origin (0,0)
- NSImage/CGImage: Bottom-left origin (0,0)
- SwiftUI: Top-left origin (0,0)
- Transformations needed between systems:
  1. Vision → Screen: Flip Y coordinate
  2. Screen → Image: Direct mapping
  3. Image → View: SwiftUI handles automatically

### Notification System
- Uses NotificationCenter for event propagation
- Key notifications:
  - boardDetected: Sends detected board rectangle and confidence score
  - captureStateChanged: Updates capture status
  - capturedFrame: Delivers processed frames
  - boardCoordinatesDetected: Reports coordinate detection
  - detectionStats: Reports performance metrics

## Design Patterns

### MVVM Architecture
- ScreenCapture: Model layer handling capture logic
- ScreenCaptureViewModel: View model managing UI state
- ContentView: SwiftUI view for user interface

### Observer Pattern
- NotificationCenter for loose coupling
- Enables modular component communication
- Supports async event handling

### Error Handling
- Custom ScreenCaptureError enum
- Comprehensive error cases
- Proper error propagation

## Technical Decisions

### Vision Framework
- Primary tool for board detection
- Provides rectangle and text detection
- Handles various board orientations
- Requires coordinate system transformation

### Pattern Recognition
- Focus on larger detection areas
- Use width as reference measurement
- Extract square board from top portion
- Maintain aspect ratio constraints

### Performance Considerations
- Dedicated dispatch queue for frame processing
- Efficient memory management
- Proper resource cleanup
- Single observation optimization

## Future Patterns

### Planned Implementations
1. Board Position Analysis
   - ML model integration
   - Piece detection system
   - Position validation

2. Move Analysis
   - Stockfish integration
   - Real-time evaluation
   - Visual overlay system

3. State Management
   - Game state tracking
   - Move history
   - Analysis persistence

## Testing Patterns

### Unit Testing
- ScreenCapture functionality
- Board detection accuracy
- Coordinate recognition

### Integration Testing
- End-to-end capture workflow
- Vision framework integration
- Notification system

### UI Testing
- SwiftUI interface validation
- User interaction flows
- Error state handling