software requirements specification - web services v5.pdf

8/18/2019 Software Requirements Specification - Web services v5.pdf

1/17

KLIKseeSoftware Requirements Specification

Nicola De Franceschi, CTO

Introduction 2.........................................................................................

Definitions 3...................................................................................................

Overall description

3..............................................................................

Application

3..................................................................................................Website 4........................................................................................................

Users 4............................................................................................................

Specific requirements - Application 5....................................................

User interface

5..............................................................................................

Server communication 8.................................................................................

Movie recognition 8........................................................................................

Media player communication

9......................................................................Windows versions compatibility 10...............................................................

Specific requirements - Website 11........................................................

Website content 11.........................................................................................

Login

12..........................................................................................................

Social networks 12..........................................................................................

Specific requirements - Server and database 13.....................................

Server architecture

13.....................................................................................

Database design

14.........................................................................................

Server API

15.................................................................................................

Performance requirements 16........................................................................

Use Cases - Application 16.....................................................................

Appendix 17...........................................................................................

Sidebar contents list policy 17........................................................................


2/17

Introduction

This document contains the specifics of the web services to be developed for KLIKsee.

This document contains the specification of all the software that KLIKsee will consists of. In

this way it will be easier to understand how KLIKsee will work and the interactions between

its parts.

However, the implementations required from the supplier is limited to the following:

• Implementation of the databases as described later.

• The website layouts for the different web pages will be provided by an external web

agency as static HTML-CSS pages with placeholders for images and texts. It is required

to replace them with dynamic content retrieved by the database.

• The implementation of the web API needed for the client application (developed by an

external company), as expressed in high level of abstraction here and to be designed

together by 1) web services supplier, 2) client application supplier and 3) the KLIKsee

CTO.

• Deployment on a test environment (for internal test usage) and the production

environment.

• Testing

It’s is required to have access to the implemented code during all phases of development by

the KLIKsee CTO. This will allow early detection of misunderstanding.

KLIKSEE SOFTWARE REQUIREMENTS SPECIFICATION 2


3/17

Definitions

Overall description

Application

The KLIKsee application will run on the user’s computer and will allow her to explore the

contents she sees in movies while watching them.

It will run in the background without interaction with the user for most of the time, listening

for notifications provided by the different media players. When the user starts playing a movie

in full screen, the KLIKsee application will provide access to the contents displayed on screen

for any given time. The users will then have the ability to like the content, mark them as

favourite, open its websites or buy it.

The user can at any time pause the movie and open a contents window, that displays all the

content that is in the movie currently playing.

The user will have the ability to login in or sign up to KLIKsee.

Term Definition

KLIKsee application The client software the runs in the users computer, interacts with the mediaplayers the user installs and uses, and displays the graphical interface during themovie playback.

KLIKsee website The website on which the user can login, see her private/public pages, hersettings, explore movies and contents, etc.

Application user User that downloaded and uses the KLIKsee application on her computer

Website user User that registered on the KLIKsee website

Website guests User that visits the KLIKsee website, but didn’t yet registered to KLIKsee

Movie database Database that contains all the informations about the movies and the contents inthem

Movie analyst Member of the KLIKsee team whose job is the retrieve informations about thecontent seen in movies and enter them in the Movie database

Media player orMovie provider

Application on the users computer that she uses to watch movies (e.g. iTunes,Windows media player, VLC, …), by downloading or streaming them. Itincludes also websites (e.g. Netflix)

Movie content Products, locations, cultural informations related to the each movie scene.

Movie version Multiple version of the same movie can exists due to different movie providers.Differences can introduces offset between two movie versions

Reference movie For each movie, the version that was used to add content by KLIKsee analysts,and that is taken as a reference from which the others versions’ time should besynched to



4/17

Website

The KLIKsee website will contains all the informations about the contents of movies and the

user experience on KLIKsee.

The functions provided are listed here:

Users

Function Description

Favorites contents The users can see the contents she mark as favorite during the movie and add orremove favorite contents while exploring the KLIKsee website

Shared content The user will be able to share the content on social networks

Movies watched The user can see a list of the movies she watched

Top movies The user will see the list of top movies integrated with the KLIKsee experience,based on movies seen by other KLIKsee users

Movie suggestions The user can be suggested about movies to watch based on the movies watched

Top contents The user will see the top contents based on content other KLIKsee usersmarked as favorite

Friends activity The user can explore the activity on KLIKsee that her friends make publicavailable to others, such as favorite contents, shared content, movies watched

Account information The user will be able to see her account information, and link accounts on othersocial networks in order to have more functionalities such as sharing and friends

connections

Content information Each content will have different information associated with it, such as websitelink (or links), buy link (or links), a brief description, related and similar contents,movies this content is in

User Description

Guest user User that didn’t sign up on KLIKsee yet, and hence it doesn’t have access to allthe features of KLIKsee

KLIKsee user User that singed up on KLIKsee and has access to all the features of KLIKsee

Analyst user Member of KLIKsee authorised to add movies and contents



5/17

Specific requirements - Application

User interface



6/17

The application will have two main interface components, a sidebar and a contents window

(see images above).

During normal playback of a movie in fullscreen mode, only a small KLIKsee logo will be

present in the top right corner of the screen. The sidebar will appear when the user wants to

have access to it. It can do that by either clicking on the logo, or move the mouse pointer on

the left side.

The sidebar will show an header, the contents list, and a footer. The header will contains the

KLIKsee logo, the footer will show a button that opens the content window, and the content

list shows the contents of the movies in chronological order, with the last seen content on the

top of the list. Content that didn’t yet appeared on screen will not be present in the list, and

the list will updated every time new content will be shown.

For each content, are provided four icon buttons that allows the user to mark the item asfavourite, open the related website, go to a e-commerce website to buy or share, respectively.

Full details about the sidebar content policy is detailed in the appendix.

Clicking on a content will open a small window that contains informations about the item,

such as pictures, description, link for the website, link for buying, share button. This window

will be semitransparent like the sidebar and the contents window, and will have an interface

like in the following figure.

On the sidebar footer there will be a button used by the user whenever she finds a content

that is not been tagged by KLIKsee analysts and she wants to add that information herself.

She will then click the “add tag” button, that will open a dialog window where she can insert

the name of the content and optionally a brief description and send that to our analysts for

review, together with the movie info and the time position in the movie at which the contentappears.

Content info

Title

Lorem ipsum dolor sit amet, consectetur adipisci

elit, sed eiusmod tempor incidunt ut labore et dolore

magna aliqua. Ut enim ad minim veniam, quis

nostrud exercitation ullamco laboris nisi ut aliquid ex

ea commodi consequat. Quis aute iure

reprehenderit in voluptate velit esse cillum dolore eu

fugiat nulla pariatur. Excepteur sint obcaecat

cupiditat non proident, sunt in culpa qui officia

deserunt mollit anim id est laborum.



7/17

The contents window contains a header and the contents grid. The header contains the

KLIKsee logo, content filter options, search field and link to the KLIKsee website.

The content window will be open automatically when the movie finishes, or when the user

click the contents window button on the sidebar. When opening, the interface will take place

on top of the movies, fullscreen. If the movie is playing, it will pause the movie and start

playing back when the user exits the window.

The contents grid contains all the contents in the movie, in chronological order, with the first

seen content on the top.

Passing the mouse on top of each content will show the content name and the four buttons as

in the sidebar.

All the links will open on an external browser.

The user will have the ability (from both the sidebar and the contents window) to open the

application settings. The window will be divided in multiple tabs: one will allow the user to

see, add and modify the social networks account linked with her KLIKsee account; the

second tab will show the tag requests done by the user, and their status (approved or not, with

explanations); the third tab will include general settings; the last will provide the ability to log

out from the application.

The first time the user open the application, she will see a welcome window that let her log in

or sign up to KLIKsee. After logging in, and when the user opens the application by clicking

on the KLIKsee icon, a window should open that let the user see featured movie she could

watch, and her previous activity on KLIKsee. The user will have the ability to open the

KLIKsee website to interact more.



8/17

Server communication

The application will need to communicate with the server in order to get information about

the movies and related contents, and save information about the user interactions with

KLIKsee application.

Movie and contents informations contains a list of all the contents in the movie with the

temporal position of them in the movie and their informations as provided by the database.

User interactions include logs information for statistical proposes (such as when the user open

the sidebar, how many times she open the content window, when she opens a link and which

one, which movies she watch and when, etc.) and when the user mark a content as favourite

or share it.

Movie recognition

The recognition of the movie the user is watching is done using different approaches. The

informations needed to be recognise of a movie are its ID inside our database and its

synchronisation offset with the reference movie.

Due to the multitude of movies versions available to the user (they may differ for different

movie providers, DVD/Blue Rays and/or between different files downloaded with torrents orobtained by other means), it’s very important to establish a synchronisation mechanism

Featured movies

Last favourited content

Open KLIKsee website

KLIKsee



9/17

between the movie the user is playing and the movie KLIKsee analysts used to add contents.

The KLIKsee application require only to know the offset between the two versions, from

which it can just apply this information in order to know when a content is actually showed

on the user’s screen. In particular, this offset could change during the movie (for example due

to the presence or absence of a scene). For this reasons the offset could be represented bystart_time-offset pairs, where start_time is the time when offset become valid; it will remain valid

until the next start_time.

The movie recognition logic will be provided and can then be considered as a black box for

the application developing proposes. The following is a UML class that describe the

recognition logic. The MovieRecognition singleton instance method recognise should be called

with the movie object to recognise. It will then be responsible to delegate the work to the

recognisers instances in order to obtain the required informations.

Media player communication

For each media player, some informations must be obtained. In particular:

recogise:(Movie)movieRecognisers

singleton classMovieRecognition

recogise:(Movie)

interfaceMovieRecogniser*

1

TitleRecogniser

HashRecogniser

AudioFingerprintRecogniser

SubtitlesRecogniser

Info Description

hasMovie boolean, whether or not the player has a movie selected, that is either paused orplaying

isPlaying boolean, valid if the player hasMovie=true, indicates whether the movie is playingor it’s paused

isFullScreen boolean, whether the player is fullscreen or not

currentMovie object identifying the movie that is currently playing

currentTime seconds from the beginning of the movie

synchedTime seconds from the beginning of the movie, synched related to the reference movie



10/17

The following describe the states and transitions between them for every media player the

user has installed on its computer.

The KLIKsee application can interact with the players buy sending play and pause

commands and ask for informations about the movie currently played and the current timeposition.

The KLIKsee application must take this informations for all the media player the users could

use, and choose from them the one that is currently playing a movie. In order to do this a

media player manager entity must control every one of them and identify the one that the

user is currently using. The following is a UML Class diagram that describe this logic. The

MediaPlayerManager and the implementations of the MediaPlayer interface will be provided by

us and can be considered as a black box from the developers point of view. Other classes that

implements the MediaPlayersManagerListener interface may register themselves to receive

notification of state changes of the media player.

Windows versions compatibility

The application has to be compatible with the following versions of Windows: Windows XP,

Windows 7, Windows 8.

Idle

Playing

PlayingFullscreen

playpausemoveTo:(seconds)

playerscurrentPlayer

singleton classMediaPlayersManager

playpausemoveTo:(seconds)

hasMovieisPlayingisFullScreencurrentMoviecurrentTimesynchedTime

interfaceMediaPlayer

*1 Movie*1

onMediaPlayerManagerStateChanged

interfaceMediaPlayersManagerListener

*

iTunes VLC Netflix …



11/17

Specific requirements - Website

The KLIKsee website will be designed by an external web agency, that will study and provide

the best layouts of the pages that composes it. Social sharing is at the core of time spent

online, and the KLIKsee website will provide social functionalities to the users, integratedwith existing social networks like Facebook, Twitter and Instagram. It will allow users to keep

track of the movies they watch via KLIKsee, items they saved and purchased as well as

discovering additional products and information by interacting with their friends, other

KLIKsee users around the world, creating a community of people that don’t just watch

movies, they live them.

The KLIKsee pages will be delivered by the external agency as static mockup HTML-CSS-

Javascript. KLIKsee developers will be responsible to make the content dynamic by obtaining

the content from either the REST API or directly by querying the database.

Website content

The website will have the following static pages that describe KLIKsee:

• General product information about the KLIKsee software,

• Links to download the application,

• The KLIKsee movie library.

The user will also have the ability to login or signup. When authenticated, other pages will beavailable with dynamic content based on the logged user:

• Home,

• My Profile,

• Friends,

• Explore,

• Account and settings.

The “Home” page will be an aggregator of the activity of the user’s friends, users will be able

to see what is ‘trending’ on KLIKsee, such as popular movie titles, actors, newest content and

newest movies, most favourite content, most shared content, most purchased content.

The “My Profile” page will be a Pinterest-like “wall” where users will be able to post whatever

they have explored with the KLIKsee software. This page will be publicly accessible,

regardless if one is a KLIKsee user or not, based on the user privacy settings. The “My

Profile” page will also contain a brief BIO and a user’s top actions, the user’s KLIKsee

history, all the contents explored and movies watched, the sharing activity and a personal

favourited and bought items. In this page KLIKsee will provide suggestions and matches of

other movies to watch and similar contents to be discovered, purchased and shared.



12/17

The “Friends” page will be populated with a user’s friends (KLIKsee users followed, Facebook

friends, Twitter, etc.). The user will also be able to sort and find other users (friends or not)

based on their movie history, to see what contents they liked and shared or purchased for each

movie.

The “Explore” page will be a library of all the KLIKsee movies/contents database. It will be

populated by all analyst generated content, user approved tagged content, the movie library,

and will be completely searchable by category, keywords, movie titles and genres. KLIKsee

will provide suggestions and similar items to explore related to the contents in a user’s library.

There will be a page of the website for every content, with images of it, a brief description,

links to the website and the shopping site, ability to add the item to the favourites, similar

products, movies the item is on, comments, friends who marked it as favourite.

Every movie will also have a details page with some info such as actors, top content in the

movie and similar movies.

Login

The users will be able to log in using either social networks accounts or by email-password

authentication.

Social networks

The KLIKsee experience will be improved by linking the user with her Twitter, Google+,

and Facebook accounts. She will have the ability to change this informations in the settings

page.



13/17

Specific requirements - Server and database

Server architecture

The server architecture will be composed, as in the figure before, by the following elements:

• CDN: Requests are automatically routed to the nearest edge location.

• S3 stores static content and resources.

• HTTP requests first handled by ELB which distributes traffic among multiple EC2

Instances. EC2 instances are scaled by Auto Scaling to automatically adjust capacity up or

down. As an alternative, NGINX can be used as proxy to allow load balancing.

• Web servers respond to users request using Spring MVC, REST is used for API (used from

KLIKsee applications)

• PostgreSQL for database, plus replicas eventually in the future, with requests cached by

Redis (or memcached). MySQL could be used as well. The database should be configured

with at least one master and one slave instance. For the movies related contents, non

relational database (such as MongoDB) will be used, so that no schema is needed to

represent different content types (product, culture, actors, music, etc.) that hence need

different proprieties

• Website content dynamically generated from web server for the main content of a page.

The content can be sent to the web browser using a technique similar to Facebook BigPipe

(https://www.facebook.com/notes/facebook-engineering/bigpipe-pipelining-web-pages-

EC2 Instance Contents

Auto Scaling

Web server +REST server

(Spring MVC)

ElasticLoad

Balancingor

NGINX

CDN Amazon

CloudFront

Amazon S3

Static file andresources

(photos, javascript,static HTML, CSS, …)

AmazonRoute 53

DNS Service

PostgreSQL+ Replicas

Redis

MongoDB+ Replicas


https://www.facebook.com/notes/facebook-engineering/bigpipe-pipelining-web-pages-for-high-performance/389414033919


14/17

for-high-performance/389414033919). Alternatively, extra content (e.g. similar products,

comments,…) can be requested after page load with AJAX. This will allow faster load of

pages with lots of dynamic content.

• The web design will be provided (HTML, javascript and CSS)

The server architecture should use preferably Amazon Web Services, or similar services from

other providers.

All communications must be encrypted with SSL.

Database design

The following is a Database ER model of the data as the specifics in this document.

SQL database

MongoDB

{ _id : int, title: string, contents:[{ start_time: int, end_time: int, content: }]}

Movie { _id : int, name: string, description: string, categories: [string], links: [string], buy_links: [string], images: [string], keywords: [string]}

Content

**

idnameemail[social networksrelated fields]

User

idid_userid_contentid_moviedate[social networksrelated fields]

Share

id_userid_contentdate

Favourite

*

1

*

1

idid_userdateactionid_contentid_movieoperating_systemmedia_player

UserActionLog

*

1

idid_userid_moviemovie_timedatecontent_namecontent_descriptionreceive_notificationapproval_responseapproved_content_id

ContentTag

*

1

action can be:

start_watching_movie,end_watching_movie,open_sidebar,open_contents_window,open_content_window,open_link,open_buy_link

id_user1id_user2

Friend

* 1


https://www.facebook.com/notes/facebook-engineering/bigpipe-pipelining-web-pages-for-high-performance/389414033919


15/17

Server API

Movies

GET /movie/:midPOST /movie

DELETE /movie/:mid

GET /movies/last

GET /movies/similar/:mid

GET /user/:uid/movies/last

GET /user/:uid/movies/suggested

GET /user/:uid/movies/friends

GET /content/:uid/movies

Contents

GET /content/:cid

POST /content

DELETE /content/:cid

GET /movie/:mid/contents

GET /contents/last

GET /contents/similar/:cid

GET /user/:uid/contents/suggested

GET /user/:uid/favourites/last

GET /user/:uid/favourites/movie/:mid

POST /user/:uid/favourite

DELETE /user/:uid/favourite/:fid

GET /user/:uid/shared/last

GET /user/:uid/shared/movie/:mid

POST /user/:uid/shared

DELETE /user/:uid/shared/:fid

Users

GET /user/:uid

POST /user

DELETE /user/:uid

GET /users/friends/:uid

POST /user/:uid/action

POST /user/:uid/tag

GET /user/:uid/tags/movie/:mid

DELETE /user/:uid/tag/:tid



16/17

Social networks

GET /user/:uid/socialnetworks

POST /user/:uid/socialnetwork

DELETE /user/:uid/socialnetwork

Performance requirements

In order to establish great performance with high number of users expected in the near

future, all the server architecture and implementation must be done with scalability in mind.

Particularly, the database should be horizontally scalable as well as vertically scalable, and the

web server should be stateless and easily scalable by addition of multiple instances.

Use Cases - Application

KLIKseeuser

Register

Login

External player

Play movie

Forgotpassword

Opensidebar

Opencontentswindow

Opensettings

Add Tagrequest

Opencontentwebsite

Opencontent shop

website

Markcontent asfavourite

Share

content

Filter content:view all/only favourite

Filter content:by category

See tagrequests

status

Add socialnetworksaccount

Applicationgeneralsettings

Logout

Socialnetwork

login



17/17

Appendix

Sidebar contents list policy

The sidebar contains a list of content, in inverse chronological order of appearance on themovie. This section will describe how the contents to be added and their order in the list has

to be selected.

First of all, the list will contain only items that are already been seen on screen, i.e. with

start_time < now. They will be ordered in chronological order by their end_time. This in order to

keep on top of the list the items last seen on the movie. However, some other informations

must be taken into account.

A content can be seen more than once in a movie. To avoid the item to be on top of the list

most of the time the user open the sidebar, the number of times the user see that item while

scrolling the list should be taken into consideration as sort of a penalty for its position. For

instance, let’s say an user sees an item that she is interested in now. Even if the item was

already be in the movie for 10 times before the time the user open the sidebar, if she never

saw the item in the list (e.g. because she didn’t open the sidebar before) than that item must be

on top of it. On the contrary, if the users has already seen that item for 4-5 times, she could

be annoyed by seeing it again. So a penalty must be choose that take into consideration the

trade off between see something too much, and not seeing it at all when I’m actually

interested on it. Different algorithm must be tried to choose the best one to use, but for a start

it could be easily implemented by subtracting a time penalty to the end_time depending on

how many time the user has seen that item in the sidebar.

Moreover, in the case of multiple appearances of an item, it must not be put in the list more

than once, and only the last item appearances must be added to the list.

The following is a self-explanatory pseudocode example of a selection and sorting policy:

all_contents = get_movie_contents()

list_contents = {}

for(Content c in all_contents){

if(c.start_time < now){

if(c.id in list_contents){

c2 = list_contents.get(c.id)

c2.end_time = max(c.end_time, c2.end_time)

}else{

list_contents.add(c)

}

}

}

list_contents.sort_by(function(Content c){

c.end_time - PENALTY * c.number_of_times_on_sidebar

})


software requirements specification - web services v5.pdf

Documents