ChessPrism/cline_docs/systemPatterns.md

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