224 lines
5.8 KiB
Markdown
224 lines
5.8 KiB
Markdown
|
# MeteorShowers App Developer Manual
|
||
|
|
|
||
|
|
## Table of Contents
|
||
|
|
1. [Architecture Overview](#architecture-overview)
|
||
|
|
2. [Core Components](#core-components)
|
||
|
|
3. [Dependencies](#dependencies)
|
||
|
|
4. [File Structure](#file-structure)
|
||
|
|
5. [Key Features](#key-features)
|
||
|
|
6. [Notifications System](#notifications-system)
|
||
|
|
7. [Location Services](#location-services)
|
||
|
|
8. [UI Components](#ui-components)
|
||
|
|
|
||
|
|
## Architecture Overview
|
||
|
|
|
||
|
|
MeteorShowers is an iOS application built using UIKit that helps users track meteor showers and provides relevant astronomical data. The app follows a traditional MVC (Model-View-Controller) architecture pattern.
|
||
|
|
|
||
|
|
### Design Patterns Used
|
||
|
|
- Singleton (LocationManager, RemindersManager)
|
||
|
|
- Delegate Pattern (LocationManagerDelegate)
|
||
|
|
- Observer Pattern (NotificationCenter for updates)
|
||
|
|
|
||
|
|
## Core Components
|
||
|
|
|
||
|
|
### Models
|
||
|
|
1. **MeteorShower**
|
||
|
|
- Properties: name, datePeak, ZHR (Zenithal Hourly Rate)
|
||
|
|
- Used to represent individual meteor shower events
|
||
|
|
|
||
|
|
2. **LocationManager**
|
||
|
|
- Singleton class managing device location
|
||
|
|
- Handles location permissions and updates
|
||
|
|
- Provides location data to TopView for calculations
|
||
|
|
|
||
|
|
3. **RemindersManager**
|
||
|
|
- Manages local notifications for meteor shower reminders
|
||
|
|
- Handles persistence of reminder settings
|
||
|
|
- Methods:
|
||
|
|
- `saveReminder(for:)`
|
||
|
|
- `removeReminder(for:)`
|
||
|
|
- `hasReminder(for:)`
|
||
|
|
- `restoreAllReminders()`
|
||
|
|
|
||
|
|
4. **AstronomicalCalculations**
|
||
|
|
- Contains moon phase calculation logic
|
||
|
|
- Enum `MoonPhase` for different moon phases
|
||
|
|
- Struct `MoonPhaseCalculation` for calculations
|
||
|
|
|
||
|
|
### ViewControllers
|
||
|
|
|
||
|
|
1. **MainViewController**
|
||
|
|
- Root view controller
|
||
|
|
- Displays list of meteor showers
|
||
|
|
- Background color: .darkMidnight
|
||
|
|
|
||
|
|
2. **ShowerDetailViewController**
|
||
|
|
- Shows detailed information about selected shower
|
||
|
|
- Manages reminder functionality
|
||
|
|
- Key UI elements:
|
||
|
|
- Reminder bell icon
|
||
|
|
- Peak date
|
||
|
|
- ZHR information
|
||
|
|
- Moon phase details
|
||
|
|
|
||
|
|
### Views
|
||
|
|
|
||
|
|
1. **TopView**
|
||
|
|
- Custom view showing astronomical data
|
||
|
|
- Dependencies:
|
||
|
|
- LocationManager
|
||
|
|
- MoonPhaseCalculation
|
||
|
|
- SunRiseSetCalc
|
||
|
|
- Features:
|
||
|
|
- Sunrise/sunset times
|
||
|
|
- Moon phase
|
||
|
|
- Location-based calculations
|
||
|
|
|
||
|
|
2. **MeteorShowerTableViewCell**
|
||
|
|
- Custom cell for meteor shower list
|
||
|
|
- Background: .lightMidnight
|
||
|
|
- Corner radius: 9pt
|
||
|
|
|
||
|
|
## Dependencies
|
||
|
|
|
||
|
|
### External Libraries
|
||
|
|
1. **Alamofire**
|
||
|
|
- Used for network requests
|
||
|
|
- Installation: Swift Package Manager
|
||
|
|
|
||
|
|
2. **SnapKit**
|
||
|
|
- Auto-layout DSL
|
||
|
|
- Used for programmatic constraints
|
||
|
|
|
||
|
|
### Frameworks
|
||
|
|
1. **UIKit**
|
||
|
|
- Main UI framework
|
||
|
|
2. **CoreLocation**
|
||
|
|
- Location services
|
||
|
|
3. **UserNotifications**
|
||
|
|
- Local notifications for reminders
|
||
|
|
|
||
|
|
## File Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
MeteorShowers/
|
||
|
|
├── App/
|
||
|
|
│ ├── SceneDelegate.swift
|
||
|
|
│ ├── AppDelegate.swift
|
||
|
|
│ └── Info.plist
|
||
|
|
├── ViewControllers/
|
||
|
|
│ ├── MainViewController.swift
|
||
|
|
│ └── ShowerDetailViewController.swift
|
||
|
|
├── Views/
|
||
|
|
│ ├── TopView.swift
|
||
|
|
│ └── MeteorShowerTableViewCell.swift
|
||
|
|
├── Models/
|
||
|
|
│ ├── MeteorShower.swift
|
||
|
|
│ ├── LocationManager.swift
|
||
|
|
│ └── AstronomicalCalculations.swift
|
||
|
|
├── Managers/
|
||
|
|
│ └── RemindersManager.swift
|
||
|
|
└── Assets.xcassets/
|
||
|
|
```
|
||
|
|
|
||
|
|
## Key Features
|
||
|
|
|
||
|
|
### Reminder System
|
||
|
|
- Set reminders 3 days before meteor shower peaks
|
||
|
|
- Persistent storage using UserDefaults
|
||
|
|
- Local notifications using UNUserNotificationCenter
|
||
|
|
- Visual feedback with bell icon
|
||
|
|
|
||
|
|
### Location Services
|
||
|
|
- Uses CoreLocation for user position
|
||
|
|
- Permission handling: "When In Use" authorization
|
||
|
|
- Fallback to Moscow coordinates if location unavailable
|
||
|
|
- Used for calculating:
|
||
|
|
- Sunrise/sunset times
|
||
|
|
- Moon phase visibility
|
||
|
|
|
||
|
|
### Astronomical Calculations
|
||
|
|
1. **Sun Calculations**
|
||
|
|
- Sunrise/sunset times based on location
|
||
|
|
- Uses UTC time zone to avoid conversion issues
|
||
|
|
|
||
|
|
2. **Moon Phase**
|
||
|
|
- Calculates current moon phase
|
||
|
|
- Shows illumination percentage
|
||
|
|
- Updates based on current date
|
||
|
|
|
||
|
|
## UI Components
|
||
|
|
|
||
|
|
### Color Scheme
|
||
|
|
- `.darkMidnight`: Main background color
|
||
|
|
- `.lightMidnight`: Secondary background color
|
||
|
|
- `.lightMidnight1`: Navigation title color
|
||
|
|
|
||
|
|
### Typography
|
||
|
|
- Navigation title: System font, large title
|
||
|
|
- Labels: System font, 12pt, weight: thin
|
||
|
|
- Time labels: System font, 12pt, weight: thin
|
||
|
|
|
||
|
|
### Layout
|
||
|
|
- Corner radius: 12pt for main views
|
||
|
|
- Standard padding: 16pt
|
||
|
|
- Icon sizes: 24x24pt
|
||
|
|
|
||
|
|
## Notifications System
|
||
|
|
|
||
|
|
### Local Notifications
|
||
|
|
- Scheduled 3 days before peak
|
||
|
|
- Unique identifier format: "meteorShower-[name]"
|
||
|
|
- Permission requested on first reminder set
|
||
|
|
- Persisted across app restarts
|
||
|
|
|
||
|
|
### Permission Handling
|
||
|
|
```swift
|
||
|
|
NSUserNotificationUsageDescription: "We'll notify you 3 days before meteor shower peaks so you don't miss the show!"
|
||
|
|
```
|
||
|
|
|
||
|
|
## Location Services
|
||
|
|
|
||
|
|
### Permission Handling
|
||
|
|
```swift
|
||
|
|
NSLocationWhenInUseUsageDescription: "We need your location to calculate accurate sunrise and sunset times for your area."
|
||
|
|
```
|
||
|
|
|
||
|
|
### Location Updates
|
||
|
|
- Accuracy level: Best
|
||
|
|
- Updates when:
|
||
|
|
1. App launches
|
||
|
|
2. Returns from background
|
||
|
|
3. Location permission granted
|
||
|
|
|
||
|
|
## Best Practices
|
||
|
|
|
||
|
|
1. **Memory Management**
|
||
|
|
- Use weak self in closures
|
||
|
|
- Proper deinitialization of observers
|
||
|
|
- Cleanup of notification requests
|
||
|
|
|
||
|
|
2. **Error Handling**
|
||
|
|
- Location fallback mechanism
|
||
|
|
- Graceful degradation of features
|
||
|
|
- User feedback for failures
|
||
|
|
|
||
|
|
3. **Performance**
|
||
|
|
- Reusable cells for list
|
||
|
|
- Efficient astronomical calculations
|
||
|
|
- Proper threading for UI updates
|
||
|
|
|
||
|
|
4. **Code Organization**
|
||
|
|
- Clear separation of concerns
|
||
|
|
- Protocol-oriented design
|
||
|
|
- Extension-based organization
|
||
|
|
|
||
|
|
## Contributing
|
||
|
|
|
||
|
|
When contributing to this project:
|
||
|
|
1. Follow the existing architecture patterns
|
||
|
|
2. Maintain consistent code style
|
||
|
|
3. Add appropriate documentation
|
||
|
|
4. Test on multiple iOS versions
|
||
|
|
5. Consider backward compatibility
|