# asura1234/dogbreedflashcard architecture

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

- Interactive diagram: https://gitdiagram.com/asura1234/dogbreedflashcard
- Repository: https://github.com/asura1234/dogbreedflashcard

## Overview

##### Project type and purpose
- This is a native iOS app (built in SwiftUI) whose purpose is to help users learn dog breeds through an interactive flash-card guessing game.
- It’s structured as a client-side application that fetches data from an external Dog API, applies core game logic, and presents a UI with sound effects and progress tracking.

##### File structure
- Top-level directories and files:
- DogBreedFlashCard.xcodeproj & workspace files (Xcode project)
- DogBreedFlashCard/Resources & UI folder (SwiftUI views, assets, audio files)
- Packages/ (three Swift Packages: GamePackage, ModelsPackage, ServicesPackage)
- scripts/ (test runners for unit and UI tests)
- Key patterns:
- Modular architecture: UI layer separated from core game logic, models, and service layers
- Each Swift package has its own Sources and Tests directories
- Use of factories (GameFactory, FakeGameFactory) and protocols for testability
- Configuration/deployment:
- .swiftlint.yml, .gitignore
- scripts/run_tests.sh & run_ui_tests.sh for CI/test automation

##### README for additional insights
- Confirms modular Swift Package architecture
- Lists core packages and their responsibilities:
- GamePackage: game flow, factory, progress tracking
- ModelsPackage: data models for breeds and images
- ServicesPackage: network service calling Dog API
- Mentions use of async/await and sound-effect assets
- Describes comprehensive test coverage (unit tests and UI tests)

a. Main components
- UI Layer (SwiftUI views in DogBreedFlashCard/UI)
- Game Logic Layer (GamePackage)
- Models Layer (ModelsPackage)
- Services/Networking Layer (ServicesPackage)
- External Service (Dog API at dog.ceo)
- Local Resources (image/audio assets)
b. Relationships and interactions
- UI sends user actions to GamePackage (e.g., “next card,” “submit guess”)
- GamePackage requests images/data from ServicesPackage
- ServicesPackage makes HTTP calls to Dog API and returns DogImage or error
- GamePackage uses ModelsPackage types (BreedAndBreedGroup, DogImage) to represent data
- GamePackage updates progress via ProgressTracker and returns results to UI
c. Architectural patterns and design principles
- Modular separation (clean layers, single responsibility per package)
- Dependency injection via factories (allows swapping real/fake services in tests)
- Async/await for asynchronous operations
- Testability (unit tests for each package, UI tests)
d. Relevant technologies/frameworks
- SwiftUI (UI Layer)
- Swift Package Manager (modular packaging)
- URLSession or equivalent (networking in ServicesPackage)
- ConfettiSwiftUI (third-party UI effect)
- XCTest (unit/UI tests)

##### Essential architectural elements
- Separate test components (unit tests, UI tests) off to one side with connectors to the modules they validate.
- Keep the layout logical: top row for UI, middle row for core logic + models, bottom row for services + external API, side bar for tests and resources.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        App["DogBreedFlashCardApp"]:::ui
        MainView["MainGameView"]:::ui
        CardView["CardView"]:::ui
    end

    %% Domain/Game Logic Layer
    subgraph "Game Logic Layer (GamePackage)"
        direction TB
        Game["DogBreedGuesserGame"]:::domain
        Factory["DogBreedGuessterGameFactory"]:::domain
        FakeFactory["FakeDogBreedGuesserGameFactory"]:::domain
        Tracker["ProgressTracker"]:::domain
    end

    %% Models Layer
    subgraph "Models Layer (ModelsPackage)"
        direction TB
        BreedGroup["BreedAndBreedGroup"]:::model
        DogImage["DogImage"]:::model
    end

    %% Services Layer
    subgraph "Services/Networking Layer (ServicesPackage)"
        direction TB
        APIService["DogAPIService"]:::service
    end

    %% External API
    ExternalAPI["Dog API\n(dog.ceo)"]:::external

    %% Resources
    subgraph "Local Resources"
        direction TB
        Assets["Assets.xcassets"]:::resource
        SoundCorrect["correct_sound_effect.mp3"]:::resource
        SoundIncorrect["incorrect_sound_effect.mp3"]:::resource
    end

    %% Tests
    subgraph "Tests"
        direction TB
        UITests["DogBreedFlashCardUITests"]:::test
        GameTests["GamePackageTests"]:::test
        ModelTests["ModelsPackageTests"]:::test
        ServiceTests["ServicesPackageTests"]:::test
    end

    %% Connections: UI to Game Logic
    App -->|"launches"| MainView
    MainView -->|"submitGuess()/nextCard()"| Game
    CardView -->|"display/update card"| MainView

    %% Game Logic to Services
    Game -->|"fetchRandomDogImage() async"| APIService

    %% Services to External API
    APIService -->|-->| ExternalAPI
    ExternalAPI -->|"JSON DogImage"| APIService

    %% Services to Models
    APIService -->|"returns DogImage"| DogImage
    APIService -->|"uses BreedGroup type"| BreedGroup

    %% Models to Game Logic
    BreedGroup -->|"used by"| Game
    DogImage -->|"used by"| Game

    %% Progress updates
    Game -->|"updateProgress()"| Tracker
    Tracker -->|"progressData"| MainView

    %% Resources usage
    Assets -->|"images"| CardView
    SoundCorrect -->|"play on correct"| MainView
    SoundIncorrect -->|"play on incorrect"| MainView

    %% Tests connections
    UITests -->|"UI scenarios"| MainView
    GameTests -->|"unit tests"| Game
    ModelTests -->|"unit tests"| BreedGroup
    ServiceTests -->|"unit tests"| APIService

    %% Click Events
    click App "https://github.com/asura1234/dogbreedflashcard/blob/master/DogBreedFlashCard/UI/DogBreedFlashCardApp.swift"
    click MainView "https://github.com/asura1234/dogbreedflashcard/blob/master/DogBreedFlashCard/UI/MainGameView.swift"
    click CardView "https://github.com/asura1234/dogbreedflashcard/blob/master/DogBreedFlashCard/UI/CardView.swift"
    click Game "https://github.com/asura1234/dogbreedflashcard/blob/master/Packages/GamePackage/Sources/GamePackage/DogBreedGuesserGame.swift"
    click Factory "https://github.com/asura1234/dogbreedflashcard/blob/master/Packages/GamePackage/Sources/GamePackage/DogBreedGuessterGameFactory.swift"
    click FakeFactory "https://github.com/asura1234/dogbreedflashcard/blob/master/Packages/GamePackage/Sources/GamePackage/FakeDogBreedGuesserGameFactory.swift"
    click Tracker "https://github.com/asura1234/dogbreedflashcard/blob/master/Packages/GamePackage/Sources/GamePackage/ProgressTracker.swift"
    click BreedGroup "https://github.com/asura1234/dogbreedflashcard/blob/master/Packages/ModelsPackage/Sources/ModelsPackage/BreedAndBreedGroup.swift"
    click DogImage "https://github.com/asura1234/dogbreedflashcard/blob/master/Packages/ModelsPackage/Sources/ModelsPackage/DogImage.swift"
    click APIService "https://github.com/asura1234/dogbreedflashcard/blob/master/Packages/ServicesPackage/Sources/ServicesPackage/DogAPIService.swift"
    click Assets "https://github.com/asura1234/dogbreedflashcard/blob/master/DogBreedFlashCard/Resources/Assets.xcassets"
    click SoundCorrect "https://github.com/asura1234/dogbreedflashcard/blob/master/DogBreedFlashCard/Resources/correct_sound_effect.mp3"
    click SoundIncorrect "https://github.com/asura1234/dogbreedflashcard/blob/master/DogBreedFlashCard/Resources/incorrect_sound_effect.mp3"
    click UITests "https://github.com/asura1234/dogbreedflashcard/blob/master/DogBreedFlashCardUITests/DogBreedFlashCardUITests.swift"
    click GameTests "https://github.com/asura1234/dogbreedflashcard/tree/master/Packages/GamePackage/Tests/GamePackageTests/"
    click ModelTests "https://github.com/asura1234/dogbreedflashcard/tree/master/Packages/ModelsPackage/Tests/ModelsPackageTests/"
    click ServiceTests "https://github.com/asura1234/dogbreedflashcard/tree/master/Packages/ServicesPackage/Tests/ServicesPackageTests/"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef domain fill:#d4edda,stroke:#155724,color:#155724
    classDef model fill:#fff3cd,stroke:#856404,color:#856404
    classDef service fill:#ffe5b4,stroke:#8a4b08,color:#8a4b08
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#343a40,shape:cylinder
    classDef resource fill:#f8f9fa,stroke:#6c757d,color:#343a40,shape:roundrect
    classDef test fill:#f0f0f0,stroke:#343a40,color:#343a40,shape:recttopleftbottomright
```
