# apple/sample-backyard-birds architecture

> Architecture diagram of the GitHub repository apple/sample-backyard-birds, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apple/sample-backyard-birds
- Repository: https://github.com/apple/sample-backyard-birds

## Overview

##### Project type and purpose
- This is a multi-platform SwiftUI sample app (iOS/macOS, watchOS, interactive widgets) demonstrating:
- A local persistence layer powered by SwiftData (BackyardBirdsData)
- A reusable UI library built with SwiftUI (BackyardBirdsUI)
- Modular artwork via a layered Swift package (LayeredArtworkLibrary)
- Interactive widgets using App Intents
- In-app purchases via StoreKit’s ProductView and SubscriptionStoreView

A. Swift Package Modules (code + assets)
1. BackyardBirdsData
­– Contains @Model entity definitions, relationships, data-generation helpers
­– Persists to a local SwiftData store (on-device SQLite under the hood)
2. BackyardBirdsUI
­– Reusable SwiftUI Views and Styles (BackyardList, BirdIcon, SupplyGauge, etc.)
­– Depends on BackyardBirdsData for Observable models
3. LayeredArtworkLibrary
­– Asset Catalogs and composition helpers for birds, plants, buildings, clouds

B. App Targets
1. Multiplatform App
­– Entry: BackyardBirdsApp.swift
­– Imports BackyardBirdsData, BackyardBirdsUI, LayeredArtworkLibrary
­– Configures SwiftData container and injects into SwiftUI environment
­– Renders core UI, handles StoreKit ProductView & SubscriptionStoreView
2. Watch App
­– Entry: BackyardBirdsWatchApp.swift
­– Lightweight SwiftUI UI tailored for watchOS
­– Shares BackyardBirdsData models for persistence & logic
3. Widget Extension
­– Entry: WidgetsBundle.swift
­– Uses App Intents (ResupplyBackyardIntent, WidgetConfigurationIntent)
­– Displays timelines via BackyardSnapshotTimelineProvider
­– Shares BackyardBirdsData for live data

C. External Frameworks & Services
1. SwiftData
­– Underlying persistence engine for BackyardBirdsData
2. SwiftUI / Observation
­– UI framework and Observable integration for real-time updates
3. StoreKit
­– ProductView & SubscriptionStoreView for in-app purchases
4. App Intents
­– Interactive and configurable widget intents

- App Targets → import → Swift Package Modules
- App Targets ↔ SwiftData store (read/write)
- App Targets → render → SwiftUI views
- UI Views → bind → Observable models from BackyardBirdsData
- Widgets → handle → App Intents → invoke → SwiftData updates
- App Targets → request/display → StoreKit views (ProductView, SubscriptionStoreView)

##### Architectural patterns & principles
- Modularity via Swift Packages: clear separation of Data, UI, and Artwork
- MVVM-style separation: @Model classes (models) ↔ SwiftUI Views (views)
- Dependency injection: pass SwiftData container into environment
- Reuse of code across platforms: share Packages between iOS, watchOS, Widgets
- Single source of truth: persistent models are the canonical data

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top row: Swift Packages
    BD["BackyardBirdsData Package"]:::data
    BU["BackyardBirdsUI Package"]:::ui
    AL["LayeredArtworkLibrary Package"]:::artwork

    %% Data Container inside Data Package
    BDC["BackyardBirdsDataContainer"]:::data

    %% Middle row: App Targets
    MPApp["Multiplatform App Target"]:::app
    WatchApp["Watch App Target"]:::app
    WidgetsTarget["Widget Extension Target"]:::app

    %% Bottom row: External Frameworks & Services
    SD(("SwiftData Store")):::service
    SU["SwiftUI / Observation"]:::service
    SK["StoreKit"]:::service
    AI["App Intents"]:::service

    %% Imports relationships
    MPApp -->|"imports"| BD
    MPApp -->|"imports"| BU
    MPApp -->|"imports"| AL

    WatchApp -->|"imports"| BD
    WatchApp -->|"imports"| BU

    WidgetsTarget -->|"imports"| BD

    %% Data flow to persistence
    MPApp -->|"reads/writes models"| SD
    WatchApp -->|"reads/writes models"| SD
    WidgetsTarget -->|"reads/writes models"| SD

    %% Render and bind
    MPApp -->|"renders UI"| SU
    WatchApp -->|"renders UI"| SU

    BU -->|"binds to observable models"| BD

    %% Widgets intents
    WidgetsTarget -->|"handles intents"| AI
    AI -->|"invokes updates"| SD

    %% In-app purchases
    MPApp -->|"presents purchase UI"| SK

    %% Data container to store
    BDC -->|"persists via"| SD

    %% Click Events
    click BD "https://github.com/apple/sample-backyard-birds/blob/main/BackyardBirdsData/Package.swift"
    click BDC "https://github.com/apple/sample-backyard-birds/blob/main/BackyardBirdsData/General/BackyardBirdsDataContainer.swift"
    click BU "https://github.com/apple/sample-backyard-birds/blob/main/BackyardBirdsUI/Package.swift"
    click AL "https://github.com/apple/sample-backyard-birds/blob/main/LayeredArtworkLibrary/Package.swift"
    click MPApp "https://github.com/apple/sample-backyard-birds/blob/main/Multiplatform/BackyardBirdsApp.swift"
    click WatchApp "https://github.com/apple/sample-backyard-birds/blob/main/Watch/BackyardBirdsWatchApp.swift"
    click WidgetsTarget "https://github.com/apple/sample-backyard-birds/blob/main/Widgets/WidgetsBundle.swift"

    %% Styles
    classDef data fill:#D0E8FF,stroke:#339,stroke-width:2px
    classDef ui fill:#E0F8D8,stroke:#393,stroke-width:2px
    classDef artwork fill:#FFE5B4,stroke:#E68000,stroke-width:2px
    classDef app fill:#F2F2F2,stroke:#AAA,stroke-width:2px
    classDef service fill:#E8D0FF,stroke:#933,stroke-width:2px
```
