Project Structure

Understanding the Breeze iOS app organization and file structure

Breeze follows a clean, modular architecture organized into logical directories. The project contains 24 Swift files organized across 7 main directories.

Directory Overview

App/

Application entry point and root views

Models/

Data structures and business logic

Services/

API communication and data fetching

ViewModels/

State management and business logic

Views/

SwiftUI views and components

Extensions/

Swift extensions and utilities

Resources/

Assets, colors, and resources

Complete File Structure

BreezeApp Project Structure

BreezeApp/
├── App/
│   ├── BreezeApp.swift           # App entry point (@main)
│   └── ContentView.swift         # Root container view
├── Models/
│   ├── AirQuality.swift          # Air quality data models
│   ├── AppearanceMode.swift      # Theme preference model
│   ├── City.swift                # City search models
│   ├── ClimateData.swift         # Climate data models
│   ├── PollenData.swift          # Pollen data models
│   └── Pollutant.swift           # Pollutant definitions
├── Services/
│   ├── AirQualityService.swift   # Air quality API client
│   ├── ClimateService.swift      # Climate data API client
│   ├── GeocodingService.swift    # Location search API client
│   └── PollenService.swift       # Pollen data API client
├── ViewModels/
│   └── DashboardViewModel.swift  # Main dashboard state
├── Views/
│   ├── Components/
│   │   ├── AnimatedText.swift    # Animated text component
│   │   ├── HealthTipsView.swift  # Health tips display
│   │   ├── LoadingView.swift     # Loading state view
│   │   └── SettingsView.swift    # Settings modal
│   ├── Dashboard/
│   │   ├── AQICard.swift         # Main AQI display card
│   │   └── DashboardView.swift   # Main dashboard screen
│   ├── Environmental/
│   │   ├── ClimateChartView.swift # Climate trend chart
│   │   ├── PollenView.swift      # Pollen level display
│   │   └── PollutantsGrid.swift  # Pollutants grid
│   └── Search/
│       └── SearchView.swift      # City search interface
├── Extensions/
│   └── Color+Theme.swift         # Color theme extensions
└── Resources/
    └── Assets.xcassets/
        ├── AccentColor.colorset
        ├── AppIcon.appiconset
        └── Background.colorset

Directory Details

App/

The application layer containing the entry point and root composition.

BreezeApp.swift

import SwiftUI

@main
struct BreezeApp: App {
    @AppStorage("appearanceMode") private var appearanceMode: AppearanceMode = .system
    
    var body: some Scene {
        WindowGroup {
            ContentView()
                .preferredColorScheme(appearanceMode.colorScheme)
        }
    }
}

Key Files:

• BreezeApp.swift - Main app entry point with theme configuration
• ContentView.swift - Root view that composes the main UI

Models/

Pure Swift data structures conforming to Codable for API responses.

Key Files:

• AirQuality.swift - Air quality data with AQI status calculation
• City.swift - City search results from geocoding API
• ClimateData.swift - Historical temperature data points
• PollenData.swift - Pollen levels for different allergens
• Pollutant.swift - Individual pollutant readings (PM2.5, NO2, etc.)
• AppearanceMode.swift - Light/dark/system theme preference

Models are lightweight and focused on data representation. Business logic lives in ViewModels and computed properties.

Services/

All services are implemented as actors for thread-safe API communication.

Key Files:

• AirQualityService.swift - Fetches current air quality from Open-Meteo
• ClimateService.swift - Retrieves historical climate data
• GeocodingService.swift - City search and geocoding
• PollenService.swift - Pollen forecast data

Each service is a singleton actor (static let shared) ensuring thread-safe access and preventing data races.

ViewModels/

State management layer connecting services to views.

Key Files:

• DashboardViewModel.swift - Main view model managing dashboard state

The ViewModel uses @MainActor to ensure all UI updates happen on the main thread, and conforms to ObservableObject for SwiftUI reactivity.

Views/

SwiftUI views organized by feature and component type.

Subdirectories:

• Components/ - Reusable UI components (loading states, settings, health tips)
• Dashboard/ - Main dashboard screen and AQI card
• Environmental/ - Climate charts, pollen displays, pollutant grids
• Search/ - City search interface

Views are kept small and focused. Complex views are broken down into smaller, reusable components.

Extensions/

Swift extensions for additional functionality.

Key Files:

• Color+Theme.swift - Custom color definitions for AQI levels, pollen, and themes

Color Theme Example

static let aqiGood = Color(hex: "34c759")
static let aqiModerate = Color(hex: "ff9500")
static let aqiUnhealthy = Color(hex: "ff3b30")

Resources/

Asset catalog containing app icons, color sets, and other visual resources.

Contents:

• AccentColor.colorset - App-wide accent color
• AppIcon.appiconset - App icon assets
• Background.colorset - Background color for dark/light modes

File Organization Principles

Separation of Concerns

Each layer has a single responsibility:

• Models: Data representation
• Services: API communication
• ViewModels: State management and business logic
• Views: UI presentation

Feature-Based Organization

Views are organized by feature (Dashboard, Environmental, Search) making it easy to locate related files.

Reusability

Common components are extracted into the Components/ directory and can be used across different screens.

Scalability

The structure supports growth:

• New features get their own View subdirectories
• New data sources get new Service actors
• Shared models remain in Models/

Navigation Guide

1. Starting a new feature

   1. Create models in Models/ for data structures
   2. Create a service actor in Services/ for API calls
   3. Create a view model in ViewModels/ for state management
   4. Create views in appropriate Views/ subdirectory
2. Adding reusable components

   Place shared UI components in Views/Components/ for use across features.

3. Extending functionality

   Add Swift extensions in Extensions/ directory (e.g., Date+Formatting.swift).

4. Adding resources

   Place images, colors, and assets in Resources/Assets.xcassets/.

Next Steps

Design Patterns

Learn about MVVM, actors, and architectural patterns

Data Models

Explore the data models in detail