Merge pull request #334 from GCES-Jandig/333-create-architecture-docu…

…ment

[REVIEW] 333 - Create Software Architecture Document

docs/architecture-document.md

@@ -0,0 +1,113 @@
+# Revision History
+
+|Version | description| Author(s) | date |
+|--------|------------|-----------|------|
+|1.0|Initial version|Victor Gomide & Emanuel Holanda|05/10/2020| 
+|1.1|New diagrams in  PlantUml| VIctor Gomide & Emanuel Holanda |24/10/2020|
+
+
+# Software Architecture Document (SAD)
+## Introduction 
+
+This document provides a complete architectural overview of the Jandig ARte project. In it, you’ll find the goals and constraints of architecture, the use-case view, the logical view, among others.
+
+
+### Scope 
+
+This document is extremely important for understanding the project as a whole, since architecture is the basis of all software. It is not only suitable for people who want to contribute to the project, but also so that the current team can remember and even change previous architectural decisions.
+
+
+### Definitions, Acronyms, and Abbreviations
+
+- **SAD:** Software Architecture Document
+- **App:** Application
+- **MTV:** Model-Template-View
+- **PWA:** Progressive Web App
+
+
+### References
+
+ - [Jandig ARte's Wiki](https://github.com/memeLab/Jandig/wiki/Jandig-ARte-architecture)
+ - [CSUN's Software Architecture Document Template](https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=&cad=rja&uact=8&ved=2ahUKEwjX4638opzsAhXlHrkGHfRtDwkQFjALegQIARAC&url=https%3A%2F%2Fprojects.cecs.pdx.edu%2Fattachments%2Fdownload%2F3180%2FSoftware_Architecture_Document_SF.docx&usg=AOvVaw0aIZsfpWJeIJ52HMgh7nXx)
+ - [Documento de Arquitetura de Software - Facom/UFU](https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=&ved=2ahUKEwi9m7T2rpzsAhVuF7kGHVbrBYwQFjACegQIARAC&url=http%3A%2F%2Fwww.facom.ufu.br%2F~flavio%2Fpds1%2Ffiles%2F2016-01%2Frup_sad-template-documento-arquitetura.dot&usg=AOvVaw3qyZZysozErnD64wCX-vOy)
+ - [Documento de Arquitetura de Software RDI-AEE](https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=&cad=rja&uact=8&ved=2ahUKEwiE78LEr5zsAhV7GLkGHSWyAVMQFjAAegQIBRAC&url=http%3A%2F%2Frepositorio.aee.edu.br%2Fbitstream%2Faee%2F1106%2F3%2FTCC2_2018_2_GabrielLeiteDias_MatheusLimadeAlbuquerque_Apendice2.pdf&usg=AOvVaw2wXEOkYpBHmN32ChHHDgOh)
+- [The Django Book: Django's Structure](https://djangobook.com/mdj2-django-structure/)
+
+### Overview
+
+In order to explain Jandig ARte's architecture from different points of views, here's an approach of the next topics:
+
+- **Architectural Representation:** architecture of the software as a whole.
+- **Architectural Goals and Constraints:** non-functional requirements we want to achieve through Jandig.
+- **Use-Case View:** expected behavior from users of Jandig's functionalities.
+- **Logical View:** the internal organization of code, its packages, layers and classes.
+
+
+## Architectural Representation
+
+Project's main programming language is Python, through Django framework. Django uses an exclusive architecture called **MTV (Model-Template-View)**, in which **Model** represents the data layer, **Template** represents user's interface and **View** acts as an intermediary layer between them:
+
+![](images/mtv-architecture-diagram.png)
+
+Jandig ARte is a **Progressive Web App (PWA)**, which means it is an web app that has a similar use to a native mobile app. It uses **PostgreSQL** as database.
+
+
+## Architectural Goals and Constraints
+
+Jandig was created for providing a low-cost and easy-to-use augmented reality experience to artists and art contemplators. That said, the software must be:
+
+- Easy to learn, use and memorize;
+- Usable through a smartphone, allowing more people to use it;
+- No previous knowledge of programming necessary for using it;
+- Free, or cheap enough;
+- Available in different languages, so people around the world can use it;
+- Open Source, so community can work together for making it awesome!
+
+
+## Use-Case View
+### Account Access and Management
+
+The diagram below shows how account access and management is done, with users and system as actors. Please note that Visitor is an user that hasn't log in the app.
+
+![](images/use-case-diagram-user.png)
+
+
+### Artist Role
+
+The following diagram shows the application's features focused on the Artist's role.
+
+
+![](images/use-case-diagram-artist.png)
+
+
+### Other Features
+
+Below are shown some other interesting features from Jandig ARte:
+
+![](images/use-case-diagram-features.png)
+
+
+## Logical View
+### Overview
+
+Since the software is Django-based, it contains projects, apps and layers. in Jandig ARte case, we have two main apps: "core" and "users".
+
+![](images/package-diagram-logical-view.png)    
+
+
+### Architecturally Significant Design Packages
+
+#### "Profile" Class Diagram
+![](images/class-diagram-profile.png)
+
+#### "Marker" Class Diagram
+![](images/class-diagram-marker.png)
+
+#### "Artwork" Class Diagram
+![](images/class-diagram-artwork.png)
+
+#### "Object" Class Diagram
+![](images/class-diagram-object.png)
+
+#### "Exhibit" Class Diagram
+![](images/class-diagram-exhibit.png)

docs/images/plantUML/class-diagram-artwork.puml

@@ -0,0 +1,17 @@
+@startuml
+
+hide circle
+
+class "Artwork (models.Model)" as C {
+  {field} - author: models.ForeignKey()
+  {field} - marker: models.ForeignKey()
+  {field} - augmented: models.ForeignKey()
+  {field} - title: models.CharField()
+  {field} - description: models.TextField()
+  {field} - created_at: models.DateTimeField()
+  {method} + exhibits_count(self)
+  {method} + exhibits_list(self)
+  {method} + in_use(self)
+}
+
+@enduml

docs/images/plantUML/class-diagram-exhibit.puml

@@ -0,0 +1,16 @@
+@startuml
+
+hide circle
+
+class "Exhibit (models.Model)" as C {
+  {field} - owner: models.ForeignKey()
+  {field} - name: models.CharField()
+  {field} - slug: models.CharField()
+  {field} - artworks: models.ManyToManyField()
+  {field} - creation_date: models.DateTimeField()
+  {method} + __str__(self) 
+  {method} + artworks_count(self)
+  {method} + date(self)
+}
+
+@enduml

docs/images/plantUML/class-diagram-marker.puml

@@ -0,0 +1,20 @@
+@startuml
+
+hide circle
+
+class "Marker (models.Model)" as C {
+  {field} - owner: models.ForeignKey()
+  {field} - source: models.ImageField()
+  {field} - uploaded_at: models.DateTimeField()
+  {field} - author: models.CharField()
+  {field} - title: models.CharField()
+  {field} - patt: models.FileField()
+  {method} + __str__(self)
+  {method} + artworks_count(self)
+  {method} + artworks_list(self)
+  {method} + exhibits_count(self)
+  {method} + exhibits_list(self)
+  {method} + in_use(self)
+}
+
+@enduml

docs/images/plantUML/class-diagram-object.puml

@@ -0,0 +1,31 @@
+@startuml
+
+hide circle
+
+class "Object (models.Model)" as C {
+  {field} - owner: models.ForeignKey()
+  {field} - source: models.FileField()
+  {field} - uploaded_at: models.DateTimeField()
+  {field} - author: models.CharField() 
+  {field} - title: models.CharField()
+  {field} - scale: models.CharField()
+  {field} - position: models.CharField()
+  {field} - rotation: models.CharField()
+  {method} + __str__(self) 
+  {method} + artworks_count(self)
+  {method} + artworks_list(self)
+  {method} + exhibits_count(self)
+  {method} + exhibits_list(self)
+  {method} + in_use(self) 
+  {method} + xproportion(self)
+  {method} + yproportion(self)
+  {method} + xscale(self)
+  {method} + yscale(self)
+  {method} + fullscale(self)
+  {method} + xposition(self)
+  {method} + yposition(self)
+}
+
+@enduml
+
+

docs/images/plantUML/class-diagram-profile.puml

@@ -0,0 +1,14 @@
+@startuml
+
+hide circle
+
+class "Profile (models.Model)" as C {
+  {field} - user: models.OneToOneField()
+  {field} - bio: models.TextField()
+  {field} - country: models.CharField()
+  {field} - personal_site: models.UrlField()
+  {method} + create_user_profile(sender, instance, created, **kwarg)
+  {method} + save_user_profile(sender, instance, **kwargs)
+}
+
+@enduml

docs/images/plantUML/mtv-architecture-diagram.puml

@@ -0,0 +1,24 @@
+@startuml
+
+left to right direction
+
+rectangle "Client Side" as C {
+    rectangle "Django Template" as DT
+}
+
+rectangle "Server Side" as S {
+    rectangle "Django Framework" as DF {
+        rectangle "App Logic" as AL
+        rectangle "View Logic" as VL
+        rectangle "Model" as M
+    }
+    database "Database" as DB
+}
+
+DT <--> AL
+DT <--> VL
+AL <--> M
+VL <--> M
+M <--> DB
+
+@enduml

docs/images/plantUML/package-diagram-logical-view.puml

@@ -0,0 +1,22 @@
+@startuml
+
+hide circle
+
+package ArTE <<project>> {
+    package users <<app>> {
+        package "models.py" as M1 {
+            class Profile
+            class Marker
+            class Artwork
+            class Object
+        }
+    }
+
+    package core <<app>> {
+        package "models.py" as M2 {
+            class Exhibit
+        }
+    }
+}
+
+@enduml

docs/images/plantUML/use-case-diagram-artist.puml

@@ -0,0 +1,39 @@
+@startuml
+
+left to right direction
+
+actor "Artist"      as A
+actor "Other users" as OU
+
+rectangle {
+    usecase "Upload marker"                     as UC1
+    usecase "Upload object"                     as UC2
+    usecase "Create artwork"                    as UC3
+    usecase "Try artwork out"                   as UC4
+    usecase "Edit artwork"                      as UC5
+    usecase "Delete artwork"                    as UC6
+    usecase "Create exhibition"                 as UC7
+    usecase "Edit exhibition"                   as UC8
+    usecase "Delete exhibition"                 as UC9
+    usecase "View itens uploaded by Artist"     as UC10
+    usecase "Download itens uploaded by Artist" as UC11
+}
+
+' Artist's relationships
+A -- UC1
+A -- UC2
+A -- UC3
+A -- UC4
+A -- UC5
+A -- UC6
+A -- UC7
+A -- UC8
+A -- UC9
+A -- UC10
+A -- UC11
+
+' Other users' relationships
+UC10 -- OU
+UC11 -- OU
+
+@enduml

docs/images/plantUML/use-case-diagram-features.puml

@@ -0,0 +1,18 @@
+@startuml
+
+left to right direction
+
+actor "Visitor" as V
+
+rectangle {
+    usecase "Interact with exhibitions" as UC1
+    usecase "Change app language"       as UC2
+    usecase "Access help section"       as UC3
+}
+
+' Visitor's relationships
+V -- UC1
+V -- UC2
+V -- UC3
+
+@enduml

docs/images/plantUML/use-case-diagram-user.puml

@@ -0,0 +1,39 @@
+@startuml
+
+left to right direction
+
+actor "Visitor"                     as V
+actor "User"                        as U
+actor "Jandig ArTE" <<application>> as J
+
+rectangle {
+    usecase "View registration form" as UC1
+    usecase "Register"               as UC2
+    usecase "View login form"        as UC3
+    usecase "Recover password"       as UC4
+    usecase "Login"                  as UC5
+    usecase "View home page"         as UC6
+    usecase "Edit account data"      as UC7
+    usecase "Delete account"         as UC8
+    usecase "Log out"                as UC9
+}
+
+' Visitor's relationships
+UC1 -- V
+V -- UC2
+
+' User's relationships
+UC3 -- U
+U -- UC4
+U -- UC5
+UC6 -- U
+U -- UC7
+U -- UC8
+U -- UC9
+
+' System's relationships
+UC1 -- J
+UC3 -- J
+UC6 -- J
+
+@enduml