MeteorShowers/DEVELOPER_MANUAL.md

MeteorShowers App Developer Manual

Table of Contents

1. Architecture Overview
2. Core Components
3. Dependencies
4. File Structure
5. Key Features
6. Notifications System
7. Location Services
8. 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

NSUserNotificationUsageDescription: "We'll notify you 3 days before meteor shower peaks so you don't miss the show!"

Location Services

Permission Handling

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