# larsdevans/maggol architecture

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

- Interactive diagram: https://gitdiagram.com/larsdevans/maggol
- Repository: https://github.com/larsdevans/maggol

## Overview

##### Project Type & Purpose
- This is a native iOS application (using Xcode and Swift) designed to manage a Magic: The Gathering card collection – allowing users to build decks and share them.
- The README succinctly hints at its purpose. The file tree, with clearly separated modules for cards, collections, notifications, and services, reinforces the focus on managing card-related data and user interactions.

##### Analyzing the File Structure
- Top-Level Structure: The primary directories include the main Xcode project files (Maggol.xcodeproj) and an Application directory where most source files reside.
- Application Directory:
- Controllers: Contains controller logic (e.g., CardController.swift) to handle user interactions and route requests.
- Features/Collection: This area is divided into subfolders for Delegates, Models, ViewModels, and Views. It suggests an MVVM (Model-View-ViewModel) design pattern used specifically for the collection management feature.
- Features/Notification: Contains files such as SetReleaseNotification.swift, indicating specialized functionality for scheduling or handling notifications.
- Services: Hosts classes like DataService.swift, MagicService.swift, and NotificationService.swift to encapsulate domain-specific logic (data persistence, API interactions with Magic related services, and iOS notifications respectively).
- Utilities: Contains helper functionality (like ManaSymbolConverter.swift) that supports domain-specific transformations or conversions.

- Main Components:
- Application Entry: Represented by MaggolApp.swift as the starting point.
- User Interface Layer: Include the Controllers (e.g., CardController) and collection-specific Views (CardCreateView, CardDetailView, CardEditView, CollectionView) along with corresponding ViewModels (CardViewModel, CollectionViewModel). This layer manages user input and UI rendering.
- Business Logic / Feature Modules:
▪ The Collection module, split into Models (Card, CardImage) that hold data structure.
▪ The Notification feature managing alerts (using SetReleaseNotification).
- Services Layer:
▪ DataService handles data persistence.
▪ MagicService deals with any Magic: The Gathering specific API interactions or business processes.
▪ NotificationService manages system notifications.
- Utilities: Houses helper functions like ManaSymbolConverter for domain-specific symbol conversion.
- External Dependencies: Although not explicit, note use of Xcode’s asset catalogs and project configuration management.
- Test Suite: Represent the test target (MaggolTests) validating core functionality (example, MagicServiceTests.swift).

- Relationships & Data Flow:
- How Controllers receive user events and forward them to the business logic layer.
- In the collection feature, illustrate the MVVM interaction: Views bind to ViewModels, and ViewModels update Models.
- That Services such as DataService and MagicService underpin critical business logic and data operations.
- That NotificationService and the Notification feature are responsible for scheduling or reacting to game-related events or release notifications.

- Architectural Patterns Highlighted:
- MVVM Pattern: Clear separation of Views, ViewModels, and Models in the Collection feature.
- Modular Separation: Distinct modules for handling notifications, business logic (services), and application utilities.
- Clean Separation of Concerns: Controllers focus on input routing with dedicated services handling domain-specific tasks.

- External components (like asset catalogs or any external dependencies that might be consumed) distinctively.
- Design principles (such as dependency inversion if the Services are injected into the ViewModels or Controllers).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Entry
    subgraph "Application Entry"
        App["MaggolApp.swift"]:::entry
    end

    %% User Interface Layer
    subgraph "User Interface Layer"
        CardCtrl["CardController"]:::ui
    end

    %% Collection Feature (MVVM)
    subgraph "Collection Feature (MVVM)"
        subgraph "Models"
            Card["Card"]:::business
            CardImg["CardImage"]:::business
        end
        subgraph "ViewModels"
            CardVM["CardViewModel"]:::business
            CollVM["CollectionViewModel"]:::business
        end
        subgraph "Views"
            CardCreate["CardCreateView"]:::ui
            CardDetail["CardDetailView"]:::ui
            CardEdit["CardEditView"]:::ui
            CollectionView["CollectionView"]:::ui
        end
        Delegate["CardDelegate"]:::ui
    end

    %% Notification Feature
    subgraph "Notification Feature"
        SetRelease["SetReleaseNotification"]:::business
    end

    %% Services Layer
    subgraph "Services Layer"
        Data["DataService"]:::services
        Magic["MagicService"]:::services
        NotifService["NotificationService"]:::services
    end

    %% Utilities
    subgraph "Utilities"
        Mana["ManaSymbolConverter"]:::utilities
    end

    %% Test Suite
    subgraph "Test Suite"
        MagicTests["MagicServiceTests"]:::tests
    end

    %% Relationships
    App -->|"starts"| CardCtrl
    CardCtrl -->|"delegates_to"| Delegate
    CardCtrl -->|"launches"| CollectionView

    %% UI to ViewModel bindings within Collection Feature
    CardCreate -->|"binds_to"| CardVM
    CardDetail -->|"binds_to"| CardVM
    CardEdit -->|"binds_to"| CardVM
    CollectionView -->|"binds_to"| CollVM

    %% ViewModels using Models
    CardVM -->|"populates"| Card
    CardVM -->|"populates"| CardImg
    CollVM -->|"manages"| Card

    %% ViewModels interacting with Services
    CardVM -->|"fetches_via"| Data
    CardVM -->|"fetches_via"| Magic
    CollVM -->|"fetches_via"| Data
    CollVM -->|"fetches_via"| Magic

    %% Services interaction with Notification Feature
    Magic -->|"triggers"| NotifService
    NotifService -->|"schedules"| SetRelease

    %% Utility usage
    CardVM -->|"utilizes"| Mana

    %% Test Suite targeting Services
    MagicTests -->|"tests"| Magic

    %% Click Events
    click App "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/MaggolApp.swift"
    click CardCtrl "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Controllers/CardController.swift"
    click Card "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Features/Collection/Models/Card.swift"
    click CardImg "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Features/Collection/Models/CardImage.swift"
    click CardVM "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Features/Collection/ViewModels/CardViewModel.swift"
    click CollVM "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Features/Collection/ViewModels/CollectionViewModel.swift"
    click CardCreate "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Features/Collection/Views/CardCreateView.swift"
    click CardDetail "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Features/Collection/Views/CardDetailView.swift"
    click CardEdit "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Features/Collection/Views/CardEditView.swift"
    click CollectionView "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Features/Collection/Views/CollectionView.swift"
    click Delegate "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Features/Collection/Delegates/CardDelegate.swift"
    click SetRelease "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Features/Notification/SetReleaseNotification.swift"
    click Data "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Services/DataService.swift"
    click Magic "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Services/MagicService.swift"
    click NotifService "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Services/NotificationService.swift"
    click Mana "https://github.com/larsdevans/maggol/blob/main/Maggol/Application/Utilities/ManaSymbolConverter.swift"
    click MagicTests "https://github.com/larsdevans/maggol/blob/main/MaggolTests/MagicServiceTests.swift"

    %% Styles
    classDef entry fill:#E8DAEF,stroke:#7D3C98,stroke-width:2px;
    classDef ui fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef business fill:#ABEBC6,stroke:#229954,stroke-width:2px;
    classDef services fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef utilities fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px;
    classDef tests fill:#F5B7B1,stroke:#CB4335,stroke-width:2px;
```
