[93] Add dev guide details

* Add architecture description * Add UI component description * Add Logic details * Add Model and Storage details * Add sequence diagrams * Refine SD description * Updated SD lifeline * Update pptx file with SDs
Alaru · Sep 25, 2016 · 86f812b · 86f812b
1 parent 29ad56d
commit 86f812b
Show file tree

Hide file tree

Showing 8 changed files with 93 additions and 12 deletions.
diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md
@@ -37,27 +37,103 @@
 
 ## Design
 
-<img src="images/Architecture.png" width="600">
+<img src="images/Architecture.png" width="600"><br>
+The **_Architecture Diagram_** given above explains the high-level design of the App.
+Given below is a quick overview of each component.
 
-### Main
+`Main` has only one class called [`MainApp`](../src/main/java/seedu/address/MainApp.java). It is responsible for,
+* At app launch: Initializes the components in the correct sequence, and connect them up with each other.
+* At shut down: Shuts down the components and invoke clean up method where necessary.
 
-### UI Component
+[**`Commons`**](#common-classes) represents a collection of classes used by multiple other components.
+Two of those classes play an important role at the architecture level.
+* `EventsCentre` : This class (written using [Google's Event Bus library](https://github.com/google/guava/wiki/EventBusExplained)
+  is used to communicate between components using events (i.e. a form of _Event Driven_ design)
+* `LogsCenter` : Used by many classes to get log information to the App's log files.
 
-<img src="images/UiClassDiagram.png" width="800">
+The rest of the App consists four components.
+* [**`UI`**](#ui-component) : The UI of tha App.
+* [**`Logic`**](#logic-component) : The command executor.
+* [**`Model`**](#model-component) : Holds the data of the App in-memory.
+* [**`Storage`**](#storage-component) : Reads data from, and writes data to, the hard disk.
 
-### Logic Component
+Each of the four components
+* Defines its _API_ an interface with the same name as the Component. `Logic.java`
+* Exposes its functionality using a `{Component Name}Manager` class e.g. `LogicManager.java`
 
-<img src="images/LogicClassDiagram.png" width="800">
+The _Sequence Diagram_ below shows how the components interact for the scenario where the user issues the
+command `delete 3`.
 
-### Model Component
+<img src="images\SDforDeletePerson.png" width="800">
 
-<img src="images/ModelClassDiagram.png" width="800">
+>Note how the `Model` simply raises a `ModelChangedEvent` when the model is changed,
+ instead of asking the `Storage` to save the updates to the hard disk.
 
-### Storage Component
+The diagram below shows how the `EventsCenter` reacts to that event, which eventually results in the updates
+being saved to the hard disk. <br>
+<img src="images\SDforDeletePersonEventHandling.png" width="600">
 
-<img src="images/StorageClassDiagram.png" width="800">
+> Note how the event is propagated through the `EventsCenter` to the `Storage` without `Model` having
+  to be coupled to the `Storage`. This is an example of how this Event Driven approach helps us reduce coupling
+  between components.
 
-### Commons Component
+The sections below give more details of each component.
+
+### UI component
+
+<img src="images/UiClassDiagram.png" width="800"><br>
+
+**API** : [`Ui.java`](../src/main/java/seedu/address/ui/Ui.java)
+
+The UI consists of a `MainWindow` that is made up of parts e.g.`CommandBox`, `ResultDisplay`, `PersonListPanel`,
+`StatusBarFooter`, `BrowserPanel` etc. All these, including the `MainWindow` inherits from the abstract `UiPart` class
+and they can be loaded using the `UiPartLoader`.
+
+The `UI` component uses JavaFx UI framework. The layout of these UI parts are defined in matching `.fxml` files
+ that are in the `src/main/resources/view` folder.<br>
+ For example, the layout of the [`MainWindow`](../src/main/java/seedu/address/ui/MainWindow.java) is specified in
+ [`MainWindow.fxml`](../src/main/resources/view/MainWindow.fxml)
+
+The `UI` component,
+* Executes user commands using the `Logic` component.
+* Binds itself to some data in the `Model` so that the UI can auto-update when data in the `Model` change.
+* Responds to events raises from various parts of the App and updates the UI accordingly.
+
+### Logic component
+
+<img src="images/LogicClassDiagram.png" width="800"><br>
+
+**API** : [`Logic.java`](../src/main/java/seedu/address/logic/Logic.java)
+
+1. `Logic` uses the `Parser` class to parse the user command.
+2. This results in a `Command` object which is executed by the `LogicManager`.
+3. The command execution can affect the `Model` (e.g. adding a person) and/or raise events.
+4. The result of the command execution is encapsulated as a `CommandResult` object which is passed back to the `Ui`
+
+### Model component
+
+<img src="images/ModelClassDiagram.png" width="800"><br>
+
+**API** : [`Model.java`](../src/main/java/seedu/address/model/Model.java)
+
+The `Model`,
+* Stores a `UserPref` object that represents the user's preferences
+* Stores the Address Book data
+* Exposes a `UnmodifiableObservableList<ReadOnlyPerson` that can be 'observed' e.g. the UI can be bound to this list
+  so that the UI automatically updates when the data in the list change.
+* Does not depend on any of the other three components.
+
+### Storage component
+
+<img src="images/StorageClassDiagram.png" width="800"><br>
+
+**API** : [`Storage.java`](../src/main/java/seedu/address/storage/Storage.java)
+
+The `Storage` component,
+* can save `UserPref` objects in json format and read it back.
+* can save the Address Book data in xml format and read it back.
+
+### Common classes
 
 ## Testing
 
@@ -132,6 +208,7 @@ Priority | As a ... | I want to ... | So that I can...
 `* *` | user | hide [private contact details](#private-contact-detail) by default | minimize chance of someone else seeing them by accident
 `*` | user with many persons in the address book | sort persons by name | locate a person easily
 
+{More to be added}
 
 ## Appendix B : Use Cases
 
@@ -158,13 +235,17 @@ Use case ends.
 > 3a1. AddressBook shows an error message <br>
   Use case resumes at step 2
 
+{More to be added}
+
 ## Appendix C : Non Functional Requirements
 
-1. Should work on any [mainstream OS](#mainstream-os) as long as it has Java 8 or higher installed.
+1. Should work on any [mainstream OS](#mainstream-os) as long as it has Java `1.8.0_60` or higher installed.
 2. Should be able to hold up to 1000 persons.
 3. Should come with automated unit tests and open source code.
 4. Should favor DOS style commands over Unix-style commands.
 
+{More to be added}
+
 ## Appendix D : Glossary
 
 ##### Mainstream OS

diff --git a/docs/diagrams/Diagrams.pptx b/docs/diagrams/Diagrams.pptx
diff --git a/docs/images/Architecture.png b/docs/images/Architecture.png
diff --git a/docs/images/LogicClassDiagram.png b/docs/images/LogicClassDiagram.png
diff --git a/docs/images/SDforDeletePerson.png b/docs/images/SDforDeletePerson.png
diff --git a/docs/images/SDforDeletePersonEventHandling.png b/docs/images/SDforDeletePersonEventHandling.png
diff --git a/docs/images/StorageClassDiagram.png b/docs/images/StorageClassDiagram.png
diff --git a/docs/images/UiClassDiagram.png b/docs/images/UiClassDiagram.png