Potentia ITSS Project Design Documentitss/static/media/Project... · ITSS – Project Design...

Potentia ITSS

Project Design Document

Document Version: 1.0

ITSS – Project Design Document (i)

AUTHORS

This document was prepared by:

Sam Messina, Developer

Gregory Brinkman, Developer

Ayush Kohli. Developer

VERSION HISTORY

Date Document

Version Document Revision History Document Author/Reviser

Feb 23, 2018 0.0 Completed assumptions, constraints, and standards, as well as use cases and UI design specs

Sam Messina

Feb 24, 2018 0.1 Filled in section 3. Ayush Kohli

Feb 26, 2018 0.2 Added Design document at the end Ayush Kohli

Feb 27, 2018 1.0 Filled out remaining document Gregory Brinkman

APPROVALS

Date Document

Version Approver Name and Title Approver Signature

ITSS – Project Design Document Table of Contents

TABLE OF CONTENTS

1. Introduction __________________________________________________________________________ 1

2. GENERAL OVERVIEW AND DESIGN GUIDELINES/APPROACH _______________________________ 1 2.1 Assumptions / Constraints / Standards .............................................................................................. 1

3. ARCHITECTURE DESIGN _______________________________________________________________ 1 3.1 Hardware Architecture ........................................................................................................................ 1 3.2 Software Architecture.......................................................................................................................... 1 3.3 Security Architecture ........................................................................................................................... 2 3.4 Communication Architecture ............................................................................................................... 2 3.5 Performance ....................................................................................................................................... 2

4. SYSTEM DESIGN _____________________________________________________________________ 2 4.1 Use-Cases .......................................................................................................................................... 2 4.2 Database Design ................................................................................................................................ 3 4.3 Data Conversions ............................................................................................................................... 3 4.4 Application Program Interfaces........................................................................................................... 3 4.5 User Interface Design ......................................................................................................................... 3 4.6 Performance ....................................................................................................................................... 7

ITSS – Project Design Document Page 1

1. INTRODUCTION

The purpose of this document is to outline the architectures of the frontend and backend, on which the project will rely. Inside this document, the ITSS team has exhaustively mapped out functionality, style, and templates necessary for this project. For the ITSS team, it will serve as a handy reference, as all our planned design work is reflected below. For the project manager, this document corresponds to design goals in our bi-weekly sprints and helps create new stories for our software engineers to work on. Lastly this document, for Potentia Analytics, also serves as a marker for how far the project has come along since its conception and many hours of brainstorming. This is a working document, open to revisions as new challenges arise during software construction. For project members working on frontend, client-facing interfaces, sections 4.1 and 4.5 are extremely relevant. For project members working on backend, server software, sections 4.6 and 4.8 are helpful.

2. GENERAL OVERVIEW AND DESIGN

GUIDELINES/APPROACH

2.1 Assumptions / Constraints / Standards

We the development team assume the application will be considered feature-complete when all potential user actions are made possible, without major interference with bugs.

Potential constraints include the inability to modify the inner workings of our backend API calls, as we will not have access to them throughout development of the application. This separate API is a bit of a black box for us, and while we do not anticipate needing to modify its inner workings, it may prove to be a constraint on our application.

The standards for the app are mostly set by the design paradigms we have chosen for it. Coding style will conform to the style guides put out by the Angular and Django teams, respectively. API design will conform to standard REST and Domain Driven Design principles. In the event that we are lacking a standard to follow, the development team will reach out to the client to consult and decide on a standard.

3. ARCHITECTURE DESIGN

3.1 Hardware Architecture

This web application is heavily dependent on the Potentia GT Engine and as such, the heavy lifting for the algorithms is done in the Engine and this application does not need powerful hardware.

Potentia currently uses Digital Ocean for hosting and hence, this web application will also be hosted on Digital Ocean. With that, one digital ocean droplet should suffice for this application. The hardware requirements would be 8 GB RAM, 2vCPUs and 80 GB SSD. Given the application is being built in USA and Digital Ocean has hosting centers in New York and San Francisco, any of those locations will suffice for hosting. Finally, the backend and the frontend will be containerized.

3.2 Software Architecture

The frontend and backend communicate using HTTP. The frontend never directly communicates to

the engine, the requests are always passed through the backend where data is marshaled exactly as

per the requirements of the Potentia Engine. We use Django serializes to marshal data

appropriately. The study data and metadata is stored in our Backend. We only make requests to the

Engine if needed i.e if the study data has changed and hence, the study results is invalidated.


We are using SOLID design principles and applying Domain Driven Design while developing the

application. Design Patterns such as the Assembler Pattern and Factory pattern will be used because

of the wide range of serializes present.

With Domain Driven Design, the business logic for sending data across should be within the Study

class itself. This builds upon the idea of Object Oriented Programming where classes have behavior.

REST Layer <-> Service(Business Logic Layer + Assembling) <-> Database | Potentia

Engine

3.3 Security Architecture

Before being sent to the database, angular directives will be error check and validate forms ensure

clean data is passed to the backend. As part of our database design, study IDs will be abstracted

away from the user. If needed, API's can be throttled to avoid DDOS attacks. Seeing as we don’t

have to store user information and passwords, information security is not an enormous concern.

However, we are still taking steps to prevent code replication, such as minifying served files and

having remote servers run certain functions, ensuring that our private information and software

remains private.

3.4 Communication Architecture

The Angular frontend will communicate with the Django backend through HTTP. Angular services provide a helpful wrapper for making these database calls. Similarly, the Django backend will communicate with the Potentia engine through HTTP. We will be making use of GET,POST and PUT HTTP methods. We will try to adhere to REST principles while developing our HTTP API's. This ensures proper handling of data.

3.5 Performance

There are currently no required performance benchmarks or requirements. However, the ITSS team

can take steps to improve the performance of this web application. They include: minifying served

files, embedding photos into html whenever possible, and removing unnecessary server calls. As the

project progresses, we will review both software and architecture in order to create a more

streamlined product.

4. SYSTEM DESIGN

4.1 Use-Cases

While our user stories have been detailed in previous documentation, the exact details of the user experience have yet to be disambiguated. In designing the user experience of the application, the ITSS team created a flowchart detailing potential user actions, as well as actions that would not be allowed. The details of this flowchart will be described here.

The application's functionality boils down to two main actions: creating "studies", and running "simulations" of those studies.

The entry point for our application is the homepage (also known as the splash page or landing page). From the landing page, users have three options:


1. They may view the available studies stored by the application

2. They may add new studies

3. They may view an "About" page, explaining more about application and how to use it.

The above three options are available in the global navigation and can be accessed from anywhere in the application.

If a user is viewing all the stored stories, they may view the study's internal structure, edit the study, delete the study, or run a simulation on the study.

While editing a study, a user may opt to discard their edits, save them to the database, or save the study and run a simulation.

When viewing the list of saved studies, a user can also create a new study, allowing them all the capabilities of editing as well.

When viewing the results of a simulation, the user can "step through" the simulation results turn-by-turn. They will also be given the option to edit the study directly from the simulation result page.

The inner workings of a study consist of four main sections:

1. The mode (whether or not the user wants to manually fill in information)

2. The study metadata (name, author, type, etc) 3. The position spectrum (a range of values detailing opinions on an issue)

4. The actors (the entities who will be taking positions on an issue)

These inner workings of a study are separated from one another when editing a study or creating a new study, so as to walk users through the process step-by-step.

4.2 Database Design

Django backend database is at the end of the document

4.3 Data Conversions

Data transfer between Angular Frontend and Django Backend should be as simplistic as possible. All

the assembling/dissembling and massaging of data will happen on the backend. Django serializes will

be utilized while adhering to the Assembler pattern to martial the data as per both Angular and

Potentia GT Engine requirements.

4.4 Application Program Interfaces

Django backend API is at the end of the document.

4.5 User Interface Design

A major overarching principle of our UI design is modularity. Because we are using Angular as a UI framework, it becomes relatively easy to divide critical sections of the application into distinct components. It is our goal to allow things like editing a study from anywhere in the application. This will be achieved by writing our edit window in a reusable, modular way.

Beyond this overarching goal, the UI should be intuitive, responsive, and informative. Mockups of the requisite views are supplied below.

(a) Splash Page


(b) Study List

(c) Study Metadata

(d) Position List


(e) Position Spectrum

(f) Actor List

(g) New Actor


(h) Study Detail

(i) Graph/Simulation Page


4.6 Performance

The app should first and foremost allow users to perform all necessary actions. Beyond this basic requirement, pages should be loaded quickly when possible, and should indicate when page load will take abnormally long with a loading icon.

Regarding backend performance, the app should return specific errors in the event something goes wrong. This error should be reflected to the user in as accurate a method possible.

While page speed isn't a huge concern across the site, all necessary steps should be taken to ensure that the application receives the highest possible page speed score on Google's PageSpeed Insights.

4.7 Classes

Django has an Object Relational Mapper with which the 'SQL' part of the database is highly abstracted and hence the low level details dont have to be specified. We will be using PostgreSQL as our database but it is not significant while development because of the ORM as the database can be easily switched out in the settings module.

Actor

• category : Individual, Country, Subnational Organization, International

Orgnaization, Other VARCHAR

• initialposition : [0,100] INT

• position : [0,100] INT

• power : [0,100] INT

• importance : [0,100] INT

• name : CHAR

• actor id : INT (PRIMARY KEY)

• study : FOREIGN KEY (ON DELETE = CASCADE)

• iteration : FOREIGN KEY (ON DELETE = CASCADE)

NOTE : Same model is being used to store actor data that is input and study result actor/voter. The foreign key determines for which parent object is this actor for. Having a relationship with iteration means its part of study result and having one for study means its related to the Study object.

Study

• id : UUID (PRIMARY KEY)

• category : Financial,Political,Security,Flow Optimization,Verification,Other

VARCHAR

• name : CHARACTERS

• question : CHARACTERS

• positions : CHARACTER (OPTIONAL)

• last updated : DATE

Study Results

• study : FOREIGN KEY (ON DELETE = CASCADE)

• iterations : INT

• median : FLOAT

• last updated : DATE

Iteration

• iterations : INT

• median : FLOAT


• steps : FOREIGN KEY (ON DELETE = CASCADE)

Offer

• from_voter : CHARACTERS

• to_voter : CHARACTERS

• accepted : BOOLEAN

• accepted_wtih : CHARACTERS

• PROBABILITY : FLOAT

• iterations : FOREIGN KEY (ON DELETE = CASCADE)

4.8 ENDPOINTS

GET /study

Parameters : None

Return:

{

"id": "UUID VALUE",

"category": "FINANCIAL",

"name": "STUDY NAME",

"question": "WHY IS SKY BLUE",

"last_updated": "01/01/2018",

"positions": "['PURPLE', 'Not Blue', 'IDK']"

"study_result": "http://api.com/study/uuid",

"actors": [{

"category": "INDIVIDUAL",

"initial_position": 0,

"position": 0,

"capability": 0,

"name": "BOB,

"salience": 0

},

{

"category": "COUNTRY",

"name": "BILL,

"initial_position": 0,

"position": 0,

http://api.com/study/uuid


"capability": 0,

"salience": 0

}

]

}

GET /study/list

Parameters : None

Return:

{

"studies": [{

"study_name": "NAME",

"study_url": "http://api.com/uuid",

"last updated": "01/01/2018"

},

{

"study_name": "NAME",

"study_url": "http://api.com/uuid",

"last updated": "01/01/2018"

}

]

}

POST /study

Parameters : All data

{


"name": "SKY COLOR",


"positions": "['Blue','Not Blue', 'IDK']",

"actors": [{


"position": 0,

http://api.com/uuid

http://api.com/uuid


"importance": 23,

"power": 100,

"name": "BOB"

}, {


"position": 100,

"importance": 3,

"power": 3,

"name": "BILL"

}

]

}

Return: URL of New Study HTTP 201

{ "url" : "http://127.0.0.1:8000/api/study/id/" }

GET /study/:id

Parameters : None

Return: Study Payload HTTP 200 or 500

{

"study_id": "54365b60-cc95-4cd6-8570-12764ae9d377",

"study_result": null,

"actors": [{

"actor_id": 1,

"name": "BOB",

"initial_position": 0.0,

"position": 0.0,

"importance": 23.0,

"power": 100.0,

"category": "INDIVIDUAL"

},

{

"actor_id": 2,

http://127.0.0.1:8000/api/study/ud/


"name": "BILL",


"position": 100.0,

"importance": 3.0,

"power": 3.0,


}

],




"last_updated": "2018-02-24T04:58:04.137001Z",

"positions": "['Blue','Not Blue', 'IDK']"

}

PUT /study/:id

Parameters : All data

{



"actors": [{

"actor_id": 1,

"name": "BOB",


"position": 0.0,

"importance": 23.0,

"power": 100.0,


}, {

"name": "NEW GUY",


"position": 3.0,

"importance": 34.0,


"power": 100.0,


}, {

"actor_id": 2,

"name": "BILL POSITION HAS DECREASED",


"position": 100.0,

"importance": 3.0,

"power": 3.0,


}],




"last_updated": "2018-02-24T04:58:04.137001Z",


}

NOTE : initial position and actor id are read only fields. Initial Position is always populated as the value of position.

Return: JSON HTTP 200

{



"actors": [{

"actor_id": 1,

"name": "BOB",


"position": 0.0,

"importance": 23.0,

"power": 100.0,


}, {


"actor_id": 2,



"position": 100.0,

"importance": 3.0,

"power": 3.0,


}, {

"actor_id": 3,

"name": "NEW GUY",


"position": 3.0,

"importance": 34.0,

"power": 100.0,


}],




"last_updated": "2018-02-24T05:00:32.432927Z",


}

GET /study/:actor_id/simulation

Parameters : None

Return: Study Result Payload HTTP 200 or 404

POST /study/:id/simulation

Parameters : NONE from UI as Django assembles the study data located in the database and fires the request

Runs simulation, updates results

Return: Study Result Payload HTTP 200

Sample Engine JSON

(a) Engine Input


Data

{'players':

b'[{"name":"BOB","initial_position":0.0,"position":0.0,"capability":"100.0","salie

nce":"23.0"},{"name":"BILL POSITION HAS

DECREASED","initial_position":100.0,"position":100.0,"capability":"3.0","salience"

:"3.0"},{"name":"NEW

GUY","initial_position":3.0,"position":3.0,"capability":"100.0","salience":"34.0"}

]'}

The above data will get put into a GET request for the Potentia Engine

(b) Engine Output

{

"median": 16.8611267541366,

"iterations": 7,

"steps": [{

"iteration": 0,

"voters": [{

"actor_actor_id": "4",

"name": "BOB",

"capability": 100.0,


"position": 0.0,

"importance": 23.0,

"TypeID": 0

}, {

"actor_actor_id": "5",


"capability": 3.0,


"Position": 100.0,

"importance": 3.0,

"TypeID": 0

}, {

"actor_id": "6",

"name": "NEW GUY",


"power": 100.0,


"Position": 3.0,

"importance": 34.0,

"TypeID": 0

}]

}, {

"iteration": 1,

"voters": [{

"actor_id": "7",

"name": "BOB",

"power": 100.0,


"Position": 37.930969084536059,

"importance": 23.0,

"TypeID": 0

}, {

"actor_id": "8",


"power": 3.0,


"Position": 37.931141498031906,

"importance": 3.0,

"TypeID": 0

}, {

"actor_id": "9",

"name": "NEW GUY",

"power": 100.0,


"Position": 3.0,

"importance": 34.0,

"TypeID": 0


}],

"median": 0,

"offers": [{

"from": "BOB",

"to": "BILL POSITION HAS DECREASED",

"prob": "1",

"accepted": true,

"with": []

}]

}, {

"iteration": 2,

"voters": [{

"actor_id": "10",

"name": "BOB",

"power": 100.0,


"Position": 37.930969084536059,

"importance": 23.0,

"TypeID": 0

}, {

"actor_id": "11",


"power": 2.97,


"Position": 12.945222183986317,

"importance": 3.0,

"TypeID": 0

}, {

"actor_id": "12",

"name": "NEW GUY",

"power": 100.0,



"Position": 10.495775794213676,

"importance": 34.0,

"TypeID": 0

}],

"median": 37.9311414980319,

"offers": [{

"from": "NEW GUY",

"to": "BILL POSITION HAS DECREASED",

"prob": "0",

"accepted": true,

"with": []

}]

}, {

"iteration": 3,

"voters": [{

"actor_id": "13",

"name": "BOB",

"power": 100.0,


"Position": 18.057623965719515,

"importance": 23.0,

"TypeID": 0

}, {

"actor_id": "14",


"power": 2.97,


"Position": 18.05756289606591,

"importance": 3.0,

"TypeID": 0

}, {

"actor_id": "15",


"name": "NEW GUY",

"power": 100.0,


"Position": 12.945222183986317,

"importance": 34.0,

"TypeID": 0

}],

"median": 12.9452221839863,

"offers": [{

"from": "BILL POSITION HAS DECREASED",

"to": "BOB",

"prob": "1",

"accepted": true,

"with": []

}, {

"from": "BILL POSITION HAS DECREASED",

"to": "NEW GUY",

"prob": "1",

"accepted": true,

"with": []

}]

}]

}

Important classes/features

Assembler of data(Potentia Engine <-> Django backend <-> Assembler <-> Frontend)

The Assembler pattern will be used to translate objects appropriately between the Frontend, Backend and Potentia GT Engine in conjunction with Django serializes. Given, there are multiple types of assemblers, the Factory pattern will be used to obtain the desired assembler.

Date:

Approved by:

Approver Signature:


Mentor Name:

Mentor Signature:

Below is a slack message with all of the comments we received in regards to this document. Approval is also inside these comments.

Potentia ITSS Project Design Documentitss/static/media/Project... · ITSS – Project Design...

Documents

Transcript of Potentia ITSS Project Design Documentitss/static/media/Project... · ITSS – Project Design...