Skip to main content
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. 
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

Each layer has a single responsibility:
  • Models: Data representation
  • Services: API communication
  • ViewModels: State management and business logic
  • Views: UI presentation
Views are organized by feature (Dashboard, Environmental, Search) making it easy to locate related files.
Common components are extracted into the Components/ directory and can be used across different screens.
The structure supports growth:
  • New features get their own View subdirectories
  • New data sources get new Service actors
  • Shared models remain in Models/
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

Build docs developers (and LLMs) love

Get started for freeTalk to us