# Graduator

* [Features](#features)
    - [Persistence](#persistence)
    - [Weighted average](#weighted-average)
    - [Deleting a `subject`](#deleting-a-subject)
    - [Changing a grade](#changing-a-grade)
    - [Creating a `subject`](#creating-a-subject)
* [Known limitations and issues](#known-limitations-and-issues)
    - [`Unit` and `subject` weight changes cancel with a delay](#unit-and-subject-weight-changes-cancel-with-a-delay)
    - [The UI is unintuitive when updating](#the-ui-is-unintuitive-when-updating)
    - [Change notifications are not implemented per se](#change-notifications-are-not-implemented-per-se)
* [Architecture](#architecture)
    - [Focusing on VMs](#focusing-on-vms)
    - [As a whole](#as-a-whole)

Graduator is an iOS application developed with SwiftUI, that helps users manage their academic `units`, `subjects`, and grades. Users can add and delete `subjects`, edit the weight and name of `subjects` and `units`, and input grades. The app displays weighted averages and explains the conditions for graduating from the Clermont Auvergne Tech Institute's mobile development BSc in 2023.

<img src="./docs/home.png" height="700" style="margin:20px" alt="view from the home page">
<img src="./docs/unit.png" height="700" style="margin:20px" alt="view from a unit page">
  
## Features

Beyond those basic features, some details need to be specified here.

### Persistence

The data is set to be persisted, unless you're using XCode's previewer canvas. 

The local persistence solution has been tested manually on the iOS Simulator.

Upon first launching the app, it is set up to load a stub.

### Weighted average

A weighted average means that a `subject` or `unit`'s weight plays a part in calculating the average. Users can observe that increasing the weight of a `subject`, for instance, will make the average of the parent `unit` tend more towards that `subject`'s grade.

<img src="./docs/weight_1.png" height="700" style="margin:20px" alt="before changing a subject's weight">
<img src="./docs/weight_2.png" height="700" style="margin:20px" alt="after changing a subject's weight">

### Deleting a `subject`

In the app, users can delete a `subject` by swiping it off the list, right-to-left.

<img src="./docs/delete_1.png" height="700" style="margin:20px" alt="deleting a subject">
<img src="./docs/delete_2.png" height="700" style="margin:20px" alt="subject deleted">

Note that when a `subject` is deleted, it is permanently removed from the system. If a user is in the process of editing and deletes a `subject`, the deletion occurs immediately upon swiping, not when they save (click 'OK'). If the user chooses to cancel their edits (click *'Annuler'*), all other unsaved changes will be discarded, but the deletion of the `subject` remains.

### Changing a grade

Before a user changes a grade, they first need to activate the `lock.open` toggle.

<img src="./docs/grade_1.png" height="700" style="margin:20px" alt="changing a grade">

After a grade was changed, in order to save the change and to see it reflected in the `unit`'s weighted average, users need to use the (`lock.open` previously) `checkmark` toggle.

<img src="./docs/grade_2.png" height="700" style="margin:20px" alt="grade changed">

### Creating a `subject`

Finally, users can create  a `subject` when in edit mode. After clicking on *"Modifier"*, look for a `+` in the top navigation bar.

<img src="./docs/delete_2.png" height="700" style="margin:20px" alt="subject deleted">
<img src="./docs/create_1.png" height="700" style="margin:20px" alt="creating a subject">
<img src="./docs/create_2.png" height="700" style="margin:20px" alt="subject created">
 
## Known limitations and issues

### `Unit` and `subject` weight changes cancel with a delay

ℹ️ **There was an issue with `subjects` getting updated even after a user presses *"Annuler"*. That issue was solved in #6**

See #7

When canceling an update to a weight, the value does not instantaneously revert to the old value, like we would expect.

If a user presses *"Modifier"* again, and then presses *"Annuler"* again, the old value finally comes back. 

We haven't found the source of the issue. The logic is the same as with names, except that simple formatters are involved. 
Canceling changes made to names is a feature that works as expected.

Since the data appears to be eventually consistent, this issue was left unsolved.

### The UI is unintuitive when updating

See #4

When updating names and weights for `units` and `subjects`, many users would expect to see a `sheet` appear. 

While we did implement that for creating a new `subject`, we did not do it for updates. Instead, the text fields used to 
display the data just become editable when the *"Modifier"* button is pressed.

### Change notifications are not implemented per se

See #5 and [this course](https://codefirst.iut.uca.fr/documentation/mchSamples_Apple/docusaurus/iOS_MVVM_guide/docs/viewModels/changeNotifications/)

Instead, "detail" views observe VMs that are higher up in the hierarchy.

```swift
import SwiftUI

struct SubjectViewCell: View {
    @ObservedObject var subjectVM: SubjectVM
    @ObservedObject var unitVM: UnitVM
    @ObservedObject var unitsManagerVM: UnitsManagerVM
        
    @State private var isGradeEditable = false

    var body: some View {
        //...
```

That way, they can propagate changes by themselves. 

```swift
Toggle("", isOn: $isGradeEditable)
    //...
    .onChange(of: isGradeEditable) { 
        //...
        subjectVM.onEdited()
        unitVM.updateSubject(subjectVM)
        try await unitsManagerVM.updateUnit(unitVM)
    } //...

```

It's clunky, it's fragile -- but it's working and so, for lack of time, it's staying for the foreseeable future.

## Architecture

### Focusing on VMs

Graduator is based on the MVVM (Model-View-ViewModel) architectural pattern. The below UML class diagram details
the structure of the models, viewmodels, and views for `UnitsManager`, `Unit`, and `Subject`. Notice how, as discussed in [this subpart](#change-notifications-are-not-implemented-per-se),
to circumvent [this issue](https://codefirst.iut.uca.fr/documentation/mchSamples_Apple/docusaurus/iOS_MVVM_guide/docs/viewModels/changeNotifications/problematic/),
we insert an entire hierarchy of VMs in certain views, so that they can update all those VMs when a detail gets edited. 
It's dirty, and it's staying that way for the foreseeable future.

```mermaid
classDiagram

    class MainView
    class UnitView
    class SubjectViewCell

    class UnitsManagerVM {
        -original: UnitsManager
        +model: UnitsManager.Data
        +isEdited: Bool
        +isAllEditable: Bool
        +updateUnit(unitVM: UnitVM): Void
        +TotalAverage: Double?
        +ProfessionalAverage: Double?
    }
    class UnitVM {
        -original: Unit
        +model: Unit.Data
        +isEdited: Bool
        +onEditing()
        +onEdited(isCancelled: Bool)
        +updateSubject(subjectVM: SubjectVM)
        +updateAllSubjects()
        +deleteSubject(subjectVM: SubjectVM)
        +addSubject(subject: Subject)
        +Average: Double?
    }
    class SubjectVM {
        -original: Subject
        +model: Subject.Data
        +isEdited: Bool
        +onEditing(): Void
        +onEdited(isCancelled: Bool): Void
    }
    
    class UnitsManager {
        +getTotalAverage(): Double?
        +getProfessionalAverage(): Double?
        +getAverage(units: Unit[]): Double?
        +data: Data
        +update(from: Data): Void
    }
    class Unit {
        +name: String
        +weight: Int
        +isProfessional: Bool
        +code: Int
        +subjects: Subject[]
        +getAverage(): Double?
        +data: Data
        +update(from: Data): Void
    }
    class Subject {
        +name: String
        +weight: Int
        +grade: Double?
        +gradeIsValid(grade: Double?): Bool
        +data: Data
        +update(from: Data): Void
    }

    MainView --> UnitsManagerVM
    UnitView --> UnitVM
    UnitView --> UnitsManagerVM
    SubjectViewCell --> SubjectVM
    SubjectViewCell --> UnitVM
    SubjectViewCell --> UnitsManagerVM

    UnitsManagerVM --> "*" UnitVM
    UnitsManagerVM --> UnitsManager
    UnitVM --> "*" SubjectVM
    UnitVM --> Unit
    SubjectVM --> Subject
```


### As a whole

It might be useful to note that, just like `UnitVM`s aggregate `SubjectVM`s, `Unit`s aggregate
`Subject`s, but these relationship between `Model` entities were removed from the diagram above for clarity.
The same is true with the `View`-related classes.

Here is the diagram with those relationships depicted, and the local persistence solution added.




```mermaid
classDiagram

    class MainView
    class UnitView
    class SubjectViewCell

    class UnitsManagerVM {
        -original: UnitsManager
        +load()
        +model: UnitsManager.Data
        +isEdited: Bool
        +isAllEditable: Bool
        +updateUnit(unitVM: UnitVM)
        +TotalAverage: Double?
        +ProfessionalAverage: Double?
    }
    class UnitVM {
        -original: Unit
        +model: Unit.Data
        +isEdited: Bool
        +onEditing()
        +onEdited(isCancelled: Bool)
        +updateSubject(subjectVM: SubjectVM)
        +updateAllSubjects()
        +deleteSubject(subjectVM: SubjectVM)
        +addSubject(subject: Subject)
        +Average: Double?
    }
    class SubjectVM {
        -original: Subject
        +model: Subject.Data
        +isEdited: Bool
        +onEditing()
        +onEdited(isCancelled: Bool)
    }


    class UnitsManager {
        -store: UnitsStore
        +save()
        +load()
        +getTotalAverage(): Double?
        +getProfessionalAverage(): Double?
        +getAverage(units: Unit[]): Double?
        +data: Data
        +update(from: Data)
    }
    class Unit {
        +name: String
        +weight: Int
        +isProfessional: Bool
        +code: Int
        +getAverage(): Double?
        +data: Data
        +update(from: Data)
    }
    class Subject {
        +name: String
        +weight: Int
        +grade: Double?
        +gradeIsValid(grade: Double?): Bool
        +data: Data
        +update(from: Data)
    }
    
    class UnitsStore {
        +load<T: Codable>(defaultValue: T[])
        +save<T: Codable>(elements: T[])
    }

    MainView --> "*" UnitView
    MainView --> UnitsManagerVM
    UnitView --> "*" SubjectViewCell
    UnitView --> UnitVM
    UnitView --> UnitsManagerVM
    SubjectViewCell --> SubjectVM
    SubjectViewCell --> UnitVM
    SubjectViewCell --> UnitsManagerVM

    UnitsManagerVM --> "*" UnitVM
    UnitsManagerVM --> UnitsManager
    UnitVM --> "*" SubjectVM
    UnitVM --> Unit
    SubjectVM --> Subject

    UnitsManager --> "*" Unit
    UnitsManager --> UnitsStore
    UnitsManager --> Stub
    Stub --> "*" Unit
    Unit --> "*" Subject
```