Complete Feature Overview
App Architecture
- SwiftUI-based iOS App with Core Data for persistence
- MVVM Architecture with ObservableObject services
- Modular structure with separate services for different functionalities
Location Tracking (LocationManager)
- Automatic GPS tracking with background updates
- Intelligent battery optimization based on battery level and Low Power Mode
- Hybrid tracking strategy: Significant Location Changes + regular updates
- Offline functionality with geocoding cache and OfflineCountryService
- Region monitoring for known locations
- Adaptive update intervals (1h, 4h, 8h, 12h, 24h)
- Automatic vs. manual mode with different tracking intensities
- Network monitoring with automatic retry mechanisms
- Exponential backoff for failed geocoding attempts
- Background task management for reliable tracking
Data Management (DataService)
- Core Data-based persistence with Stay, Country and LocationEntry entities
- Intelligent cache management with adaptive expiration times
- Batch processing for large datasets
- Conflict detection and intelligent resolution for overlapping stays
- Same-day travel detection for travel days
- Automatic country creation and day counting
- NSFetchedResultsController for efficient data queries
- Background context for heavy operations
- Data validation and error handling
Dashboard & UI (Views)
- UnifiedDashboardView: Main overview with status cards
- CurrentStatusCard: Current tracking status and country
- TopCountriesCard: Top 3 visited countries with progress bars
- TravelHistoryCard: Travel history with filter options
- TrackingProgressCard: Year progress and statistics
- Responsive design for different screen sizes
- Dark mode compatibility
Manual Entry (ManualStayEntryView)
- Retrospective stay entry with date picker
- Country selection with search functionality
- Travel details: Transport method, reference, notes
- Intelligent conflict detection and resolution
- Same-day travel support
- Transport method selection (Airplane, Car, Train, Bus, Ship, Other)
- Reference tracking (Flight numbers, license plates, etc.)
- Travel notes for additional context
History & Statistics (HistoryView)
- Year-based filtering with available years
- Country grouping with stay details
- Active vs. completed stays
- Leap year support (366 days)
- Tracking percentage per year
- Country stay groups with total days calculation
- Empty state handling for years without data
Settings (SettingsView & TrackingSettingsView)
- Location permissions with detailed explanations
- Tracking modes: Automatic vs. manual
- Battery optimization and power mode adaptation
- Data export and deletion
- App information and support
- Permission status monitoring
- Update interval configuration
- Feature overview with descriptions
Export Functionality (ExportManager)
- PDF Generator: Professional reports following Apple Design Guidelines
- CSV Export: For spreadsheet applications
- Flexible time periods: Year, month, custom date ranges
- Export preview with statistics
- Share Sheet integration
- Multiple export formats with format descriptions
- Date range validation and filtering
Country Detection
- Online geocoding with CLGeocoder
- Offline fallback with OfflineCountryService
- Persistent cache for geocoding results
- Country flags with FlagUtils
- Bounding box filter and point-in-polygon tests
- Natural Earth boundary data for offline detection
- Cache optimization with grid-based keys
Conflict Management
- Intelligent conflict detection for overlapping stays
- Automatic resolution with various strategies:
- Trim (shorten existing stays)
- Split (divide into multiple stays)
- Replace (replace existing stays)
- Same-day travel support
- User-friendly conflict resolution
- Travel type detection (same-day vs. overnight)
- Conflict resolution preview with action descriptions
User Experience
- Multilingual support with Localizable.xcstrings
- Responsive design for various screen sizes
- Intuitive navigation with SwiftUI NavigationStack
- Accessibility support
- Dark mode compatibility
- Smooth animations and transitions
- Loading states and progress indicators
Privacy & Security
- Local data storage without cloud sync
- No third-party tracking
- Transparent permission requests
- Data export for user control
- Privacy-focused design with local-only processing
- Secure data handling with Core Data encryption
Performance Optimizations
- NSFetchedResultsController for efficient data queries
- Background context for heavy operations
- Adaptive cache management
- Batch processing for large datasets
- Memory management with automatic cleanup
- Lazy loading for large datasets
- Efficient Core Data queries with proper indexing
Testing & Quality Assurance
- Unit tests for core functionalities
- UI tests for user interactions
- Error handling with user-friendly error messages
- Fallback mechanisms for offline scenarios
- Data validation and integrity checks
- Performance monitoring and optimization
Tax-Related Features
- 183-day rule monitoring with visual indicators
- Annual statistics for tax purposes
- Detailed stay protocols
- Export-friendly formats (PDF/CSV)
- Tax residency day counting with inclusive date calculation
- Country-specific stay tracking
- Professional report generation for tax advisors
Data Synchronization & Backup
- Local-only storage for privacy
- Export capabilities for data portability
- Data integrity checks and validation
- Automatic data cleanup for old entries
- Backup and restore functionality
Analytics & Reporting
- Annual tracking statistics
- Country visit frequency
- Stay duration analytics
- Travel pattern analysis
- Export statistics and summaries
- Visual progress indicators
- Historical data trends
Internationalization
- Multi-language support with comprehensive localization
- Country-specific formatting
- Currency and date formatting
- Regional settings adaptation
- Accessibility compliance
Advanced Features
- Smart conflict resolution with user choice
- Offline country detection using embedded boundary data
- Intelligent caching with adaptive expiration
- Background processing for large datasets
- Memory optimization for long-running sessions
- Error recovery mechanisms
- Data migration support
Platform Integration
- iOS system integration with background app refresh
- Share Sheet integration for exports
- Settings app integration for permissions
- Notification support for tracking status
TaxStayTracker is a comprehensive solution for automatic and manual tracking of stays in different countries, specifically developed for tax purposes, with a focus on user-friendliness, privacy, and reliability. The app provides professional-grade tracking capabilities while maintaining simplicity and ease of use for end users.
