Visual Portfolio Design Description Document - Version 1.1 - unizg
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
Visual Portfolio
Design Description Document
Version 1.1
Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
Revision History
Date Version Description Author
2017-10-26 0.1 Initial Draft Valentina, Luca
2017-11-09 1.0 First complete document Valentina, Luca, Hamza
2018-01-09 1.1 Database schema improved Valentina, Luca
Page 2
Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
1. Introduction
1.1. Purpose of this document
The purpose of this document is to describe and clarify software design of the project “Visual Portfolio”
included in the DSD course 2017/2018. This document is useful to provide a common basis for the future
development; it will also be used to guide the development of the system later.
1.2. Document organization
The document is organized as follows:
● Section 1, Introduction, describes contents of this guide, used documentation during developing
process, intended audience and scope of the project.
● Section 2, Background and Objectives, describes the background and the goals of the project.
● Section 3, High level system description, describes the system’s main components.
● Section 4, Software architecture, describes the system’s architecture modules and the technologies used
to implement them.
● Section 5, Graphical User Interface, presents the web pages models the users will interact with.
● Section 6, Database model, describes the format of the tables needed to store and retrieve data.
1.3. Intended Audience
The intended audience is:
● Team members
● Supervisors
● Customer
● New member joining the group
● Someone who will maintain or evolve the system further
1.4. Scope
This document provides high level system description and software architecture. It also describes general layout
of user interface and try to capture important design decisions the team have made in the project, and should
provide a good basis for understanding the code.
Although this document is based on user requirements, they will not be discussed in details in this document.
1.5. Definition and Acronyms
1.5.1. Definition
Keyword Definitions
User A person who uses Visual Portfolio application.
Kommuninvest employee A person who works in Kommuninvest.
Backend The system developed to manage data.
Frontend Web application that the user is going to use to analyze and
visualize portfolios.
Page 3
Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
1.5.2. Acronyms and abbreviation
Acronym or
Definitions
abbreviation
NTR Nothing to Report.
There is no information to a specific topic available or necessary.
GUI Graphical User Interface
UML Unified Modeling Language
1.6. References
1.6.1. Project Plan document
● https://www.fer.unizg.hr/_download/repository/Project_plan_-_1.0-2.pdf
1.6.2. Node.js
● https://nodejs.org/en/
1.6.3. Vue.js
● https://vuejs.org/
1.6.4. Express
● https://expressjs.com/
1.6.5. Heroku
● https://www.heroku.com/
1.6.6. Highcharts
● https://www.highcharts.com/
1.6.7. Bootstrap
● http://getbootstrap.com/
1.6.8. PostgreSQL
● https://www.postgresql.org/
1.6.9. Docker
● https://www.docker.com/
● https://hub.docker.com
1.6.10. Swagger
● https://swagger.io/
1.6.11. Docker motivation
● medium.com article about docker
Page 4
Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
2. Background and Objectives
2.1. Background
The customer for this project is Kommuninvest, a swedish local government funding agency based in Örebro,
Sweden. Kommuninvest currently has a debt management system named KI Finans. This system can be used by
their customers in order to track transactions, perform analysis and simulations, and extract exports.
The purpose of this project is to create a prototype for a visual analysis tool that can be used to show the
performance of individual debt portfolios or compare portfolios from different customers with each other and/or
financial markets. More precisely, the objective of the Visual Portfolio Project is to develop a web-based
application where users can compare different types of bond portfolios using either time-series graphs or scatter
plots. According to the client, the idea is to "give easy access to economic and financial key indicators". It
should be easy to choose the peer-group benchmarks, which indicators to analyse and how the indicators should
be displayed.
The project team will not develop the final product that Kommuninvest will use, just a prototype. The goal is
that this project will produce well-defined requirements and design that can be used by a company to implement
the final product.
2.2. Objectives
2.2.1. Summary of requirements
1. Login
2. Generate Graphs
a. Choose entity
i. Municipality
ii. Municipality group
iii. Company
b. Choose KPI (Key Performance Indicator)
c. Press Submit
3. Visualize of portfolios
4. Compare different portfolios
5. Create custom charts and tables
6. Filter the charts and data
7. Download the displayed data
8. Add data from external source by an input file
Note: for more details please see the Requirements Definitions document.
Page 5
Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
3. High level System Description
3.1. Rationale and Components’ summary
The diagram above shows how the application is decomposed and interacts with the real world. The users
(Customer, Manager, Admin) access the application through a web browser and interact with a user-friendly
graphical interface (a non-functional requirement defined in the specific document). All the features of this GUI
should be intuitive and easily understandable even at the first use.
3.1.1. Frontend
In the following text of this section, we are going to discuss our technologies choices and justify our decisions:
For the development of the client side, we decided to go with a simple and lightweight open source framework
Vue.js. It allows to build user interfaces out of simple and self-contained components using JavaScript. It allows
exploiting dual-binding between data and views and it combines best practices from famous frameworks such as
AngularJS and ReactJS. In addition, we are using CSS library, Bootstrap. It provides graphics and helpers
elements for creating responsive websites. Besides Bootstrap, the additional JavaScript library we added is
Highcharts solving the problem of creating charts in pure JavaScript, by offering an easy way of adding
interactive charts to your website or web application. Because Charts are one of the main requirements for us.
Since for the frontend we are using client-side rendering (Vue.js), backend and frontend are two separate
services running in an isolated environments and communicate through the REST API.
Page 6
Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
3.1.2. Backend
Chosen technology for developing the backend are Node.js runtime with additional web framework on top of it,
Express. Even though Node.js is quite young when compared with the alternatives for developing web based
applications, it has become one of the leading forces in the world of modern web apps. Many factors influenced
Node.js success and popularity, besides it uses dynamic and very popular script language, JavaScript, there are
other tools and features that contributed to the rapid acceptance of Node as an industry standard such as NPM
(node package manager) and its minimum configuration. Furthermore, it has an enormous community behind
and it's really well supported. Also, there are many packages available, focusing on solving common problems
modern web developers encounter, speeding up the development process by removing “boilerplate code” and
shifting focus to the business problem.
Express is a minimal and flexible Node.js web application framework that provides a robust set of features for
web. Moreover, besides Express, there are other alternative frameworks, some of them focusing specifically on
solving the problem of REST API that by definition better suits our problem. However, Express is the most
stable and trusted by the industry.
3.1.3. Database and PaaS (Platform-as-a-Service)
Since the application requires data to be persistent the question of database choice has been raised. Before even
considering a possible database, we agreed on using Code First Approach using ORM (Object relationship
mapper). Code first approach is a way of developing/generating database schema from models written in a
programming language. This way of developing databases has many benefits especially for small/medium
problems as the one we are focusing on. The biggest and most obvious value it brings to the software
stakeholders is reduced development time. Furthermore, the SQL code executed behind the scene so no
knowledge in SQL is needed (all queries are written in programming language, in our case JavaScript), also,
every query is checked before for SQL injection, removing many repeating lines of code responsible. In order to
develop software in a code first approach, we have to have an ORM. The ORM of our choice is Sequelize once
again because it’s the industry standard when working in the Node.js environment. As stated in the text before,
since SQL is completely hidden/removed for the developers database, database choice doesn’t change anything
(for our specific business problem) as long the ORM has a driver for the selected database. Furthermore, since
Heroku, the PaaS we are using for deployment of the production has a solid integration with PostgreSQL and
offers a free version we decided to take advantage of the offer.
3.1.4. Docker
In order to have unified development environment, our product is completely “dockerized”. In the other words,
backend, frontend and database run inside single docker containers as separated services. Besides three
mentioned services there is the fourth one, pgAdmin service, responsible for running visual database
management tool. Aside from all the benefits for development, one hidden advantage would be, since we have
dockerized services it’s possible to deploy those containers to production with minimum or zero configuration.
Page 7
Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
4. Software Architecture
4.1. Overview
With this type of architecture, improving the modularity of the application will be simple and this can make it
easier for developers to extend features in the future. Distinguishing among the different layers allows the
development team to program according to the interfaces, thus allowing an easier distribution of the work. So if
tomorrow customer decides to generate its own Front-end, he can easily do it. Our project is completely
developed for a customer, that might actually use it and improve it in the future.
Modularity of the project is also achieved through the implementation of REST communication between two
macro-module of the application. REST connection will be highly documented, as described in the section 4.3.
We decided to implement this software architecture because in this way all modules of our application will work
very well in cooperation, and also in order to improve at most the possible modulation of application.
When we presented our architecture to the customer, he replied that Kommuninvest actually already use a very
similar system in production, so he validated the structure of the project at all. In addition, we decided to use a
specific configuration of Docker during prototype development only, but the customer told us that
Kommuninvest production will use also for the final working product.
4.2. Layers’ description
4.2.1. Frontend
Through the implementation of Vue.js, Bootstrap and Highcharts, frontend web application provide a
user-friendly graphical user interface, that is mandatory as non-functional requirement defined in the specific
document. Through this interface, Customers, Account Managers and Administrators will be able to login into
the system and perform main activities of the application, such as compare their own portfolio with portfolios of
different type of peer group, choose between different entities (municipality, municipality group and companies)
filtering displayed data, create different type of charts, choosing to populate axis with the whole pool of data
available in database, creating an high customizable method to display data. Customers could also apply various
type of filter, and download charts in different format. In addition to that, Account Managers can see and
compare any portfolios without constraints about peer groups and can navigate through all the data saved on
database thanks to specific part of graphical user interface
Decision about how to implement our graphical user interface were based on the fact that all the features of this
application should be easily understandable and intuitive at first use. The goal of GUI is to manage a huge mass
Page 8
Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
of data contained in the database, in an agile way. This could be done thanks to the technology that we have
decided to implement, widely described in the section below. Moreover, since connection between two
macro-module must tolerate passing a lot of date, we took care also to implement and coordinate technology
able to collaborate easily and reliably.
4.2.2. REST Application
Server is composed by three separate component. We have the database for storing all the information about
entities and portfolios. PostgreSQL will be used to create the database, in order to get a modern approach to
store information in a open source object-relational database system.
Database technology will communicate with Node.js on top of Express framework in order to expose data,
provide a thin layer of fundamental web application features without obscuring Node.js and create a robust API.
All this technology is implemented in Heroku as cloud platform as a service (PaaS) that is used as a web
application deployment model. In this way we can build, deliver, monitor and scale our application easily. It’s
the fastest way to go from idea to URL, bypassing all those typical infrastructure problems.
With all this technology well implemented and coordinated, we will successfully grab a lot of data from
database and send it through REST API to frontend, where they will displayed in the best possible way.
Therefore we can achieve all non-functional requirements, such as Security, Performance, Usability and
Availability. Plus, this second macro-module is completely independent from the first described above, so it
could be implemented only for the first development and used with whatever frontend that is able to catch and
throw correct API.
Page 9
Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
4.3. Technology used
Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine. Node.js uses an event-driven,
non-blocking I/O model that makes it lightweight and efficient. Node.js' package ecosystem, npm, is the largest
ecosystem of open source libraries in the world.
Express is a minimal and flexible Node.js web application framework that provides a robust set of features for
web and mobile applications. With a myriad of HTTP utility methods and middleware at your disposal, creating
a robust API is quick and easy. Express provides a thin layer of fundamental web application features, without
obscuring Node.js features that you know and love. It’s widely tested because many popular framework are
based on it.
PostgreSQL is a powerful, open source object-relational database system. It has more than 15 years of active
development and a proven architecture that has earned it a strong reputation for reliability, data integrity, and
correctness. It runs on all major operating systems. It is fully ACID compliant, has full support for foreign keys,
joins, views, triggers, and stored procedures (in multiple languages). It includes most SQL:2008 data types. It
also supports storage of binary large objects, including pictures, sounds, or video. It has native programming
interfaces for C/C++, Java, .Net, Perl, Python, Ruby, Tcl, ODBC, among others, and exceptional documentation.
Page 10Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
We needed a platform that would allow for rapid development in our language of choice, simplified operations,
and provides great scalability. Heroku is a cloud platform as a service (PaaS) supporting several programming
languages that is used as a web application deployment model. Heroku is a cloud platform that lets build,
deliver, monitor and scale apps. It’s the fastest way to go from idea to URL, bypassing all those typical
infrastructure problems. Applications that are run on Heroku typically have a unique domain used to route
HTTP requests to the correct dyno. Each of the application containers, or dynos, are spread across a "dyno grid"
which consists of several servers. Heroku's Git server handles application repository pushes from permitted
users.
Vue.js is a progressive framework for building user interfaces. Unlike other monolithic frameworks, Vue is
designed from the ground up to be incrementally adoptable. The core library is focused on the view layer only,
and is easy to pick up and integrate with other libraries or existing projects. On the other hand, Vue is also
perfectly capable of powering sophisticated Single-Page Applications when used in combination with modern
tooling and supporting libraries. For this reason we implement it in collaboration with Bootstrap and Material
Design.
Bootstrap is an open source toolkit for developing with HTML, CSS, and JS. Quickly prototype your ideas or
build your entire app with Sass variables and mixins, responsive grid system, extensive prebuilt components,
and powerful plugins built on jQuery. Bootstrap employs a handful of important global styles and settings, all of
which are almost exclusively geared towards the normalization of cross browser styles.
Page 11Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
Material Design (codenamed Quantum Paper) is a design language developed in 2014 by Google. Expanding
upon the "card" motifs that debuted in Google Now, Material Design makes more liberal use of grid-based
layouts, responsive animations and transitions, padding, and depth effects such as lighting and shadows.
Highcharts is a charting library written in pure JavaScript, offering an easy way of adding interactive charts to
your web site or web application. Designed from ground up with mobile browsers in mind, everything from
multitouch zooming to touch-friendly tooltips responds great on mobile platforms. In modern browsers graphs
are rendered in SVG, with VML support for legacy browsers. Since Visual Portfolio main purpose is to render
chart within web application, this solution allow to do it in a great way.
Docker is a software technology providing containers. It provides an additional layer of abstraction and
automation of operating-system-level virtualization on Windows, macOS and Linux. Docker uses the resource
isolation features of the Linux kernel such as cgroups and kernel namespaces, to allow independent containers
to run within a single Linux instance, avoiding the overhead of starting and maintaining classical virtual
machines (VMs). A container image is a lightweight, stand-alone, executable package of a piece of software that
includes everything needed to run it: code, runtime, system tools, system libraries, settings. We are using this
docker paravirtualization technology for the project in order to avoid the classical monolithic approach,
implementing it with microservices and orchestrator.
Page 12Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
This allow to use resource only it’s required and “allocate” it only when are used. It’s more scalable and don’t
waste resource at all.
Since our project is developed in a distributed way, in the context of the DSD course, we decided to take
advantage of this technology in order to avoid the classical unhandy virtual machines approaches and also to
provide independence from operative system dedicated code.
General Benefits:
1. You only need Docker installed to start develop! You don’t need to install a bunch of language
environments on your machine. Want to run a Ruby script but don’t have Ruby installed? Run it in a
Ruby Docker image that you will simply pull from the DockerHub.
2. Consistent development environments among all the team members. All developers use the same
(development) OS, same system libraries, same language runtime; it doesn’t matter which actual host
OS they are running (even Windows if you can believe it).
3. It’s possible to use multiple language versions without having to resort to all the backgrounds for your
language (python, ruby, java, node).
4. The development environment is the exactly same as the production environment. This means you can
deploy and it will “just work”, and our customer ask explicitly to send the prototype together with
containers and set it up because they will use it.
5. Deployment is easy. If the docker container runs on your development machine, it will run as the same
also on the production server. Just package up your code building the Docker image for production and
deploy it on a server with Docker installed and any kind of orchestrator you like.
6. Can still use your favorite editor/IDE as you normally do. No need for running a VM in VirtualBox and
SSHing in and developing from the shell just so you can build/run on a Linux box.
Benefit in DSD course:
1. After have installed docker, “docker-compose up” and you're ready to start to code. Simple and
quick. In fact, the whole installation of the development environment (that's required on your local
machine in order to be able to develop) that's composed by: Node.js, Express framework, nodemon
(and maybe further additional libraries) will run completely inside docker containers.
2. Really small initial effort of installation and get "for free" any future development environment
upgrade. During the development process it can happen that we will add libraries and other
dependencies to our application. Using Docker, they will be automatically included and already set up
for everybody in one shot within docker containers. So, a bit of pain at the beginning and then no more.
3. Keep clean your local machine. Only docker will be installed and everything else will run bounded
inside containers. Also, you will dodge any problem of environments' conflicts.
4. Cross-OS support and everywhere the same environment. Each runtime environment (like Node.js
is) has slight differences when installed on different operative systems. Sometimes it happen that a
configuration for a library that works very well on an OS will not work at all on another.
Page 13Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
Swagger is a project used to describe and document RESTful APIs.
The Swagger specification defines a set of files required to describe such an API. These files can then be used
by the Swagger-UI project to display the API and Swagger-Codegen to generate clients in various languages.
Additional utilities can also take advantage of the resulting files, such as testing tools.
As the example shows, Swagger allow to specify how REST module of an application works. We decided to
implement it because our application has two macro-module: if the customer wants to modify one of that, he can
easily understand the interaction with the other. For example, if someone wants to modify a specific part of the
frontend, like a module of graphical user interface, he has to understand how it works with respect to the
backend. With swagger, this could be done very quickly. Since it’s highly probable that our customer will
update and improve Visual Portfolio application during time, implementation of Swagger will help. As it’s
described in the section 4.2.2, frontend and backend are completely independent and frontend could be
completely replaced with another technology able to deal with API provided by our backend.
Page 14Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
5. Graphical User Interface
Below you can find a list of few pages done so far. As mentioned, we are using an existing template based on
Bootstrap with built in Vue.js component. The template has a lot of ready components and HTML elements that
could be used in our project GUI. The template is also responsive on devices with smaller screens like Tablets
and Smartphones. This saved and will save us a lot of time later on during development. Below you can find a
set of page views that were already started:
● Image 1: Login Page: through which everyone will pass to access the application
● Image 2 and 3: Dashboard (Homepage): which is the landing page and contains main functionalities.
● Image 4: Municipalities list to be viewed by Kommuninvest Employees
● Images 5 and 6: Samples of responsiveness of our pages on smaller devices.
First Version:
1. Login interface - Graphical design rationale
Page 15Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
Images 2. and 3: Main Dashboard / Homepage / Landing page
Page 16Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
Image 4: Municipality List - Graphical design rationale
Images 5. and 6: Dashboard - Mobile web view graphical design rationale
Page 17Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
Second Version:
● Image 1 and 2: Dashboard (Homepage): which is the landing page and contains main functionalities.
● Image 3: Municipalities list to be viewed by Kommuninvest Employees
● Image 4: Kommuninvest Employee Dashboard view
Images 1 and 2: Main Dashboard - Version 2
Page 18Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
Image 2: Municipality List - Graphical design rationale - Version 2
Image 3: Kommuninvest Employee Dashboard view - Version 2
Page 19Visual Portfolio Version: 1.1
Requirements Definition Document Date: 2018-01-09
6. Database
Database schema was provided by customer with an Excel spreadsheet. The customer will use exactly the same
schema as we are using for prototype, so we decided to normalize it partially. Customer told us that the data are
not complete, and he also told us how to manage the graph with incomplete data.
We are able to access to several interesting key indicators from 2010 to 2016 (except for some periods of the
year). A municipality can always owns one or more companies, that can be of different type (Företagstyp, in
swedish means “type of companies”). Every municipality has a unique ID (Krypterad Orgnr). That allows,
looking for the Financial_Key table, to retrieve all the companies, that are in relation with that specific
municipality. Moreover, it guarantees that Kommuninvest’s Clients deal only with the economic and financial
key indicator in their own municipality group.
In the table with financial key indicators it’s possible to find economic key indicators for each company. For
some of them it’s possible to find information from 2010 to 2015, and for their debt portfolio from 2013 to
2017.
Page 20You can also read
