Client side architecture document

 Introduction
o Purpose of this document

o References

o Terms

o Document Overview

 Architectural requirements
o Non-functional requirements

 Technical platform

 Client-server communication

 Security

 Layered architecture

 Performance

 Localization

 Logging

 Local and/or cookie store in

client
 Continuous Integration

o Use Case View (functional

requirements)
 Logical View
o Tiers
  View
 Directive

 Controller (Ctrl)

 SamWise service

 Infrastructure Service

 Storage service

 Resource Service:

 ConstantService

o Modules

 Use Case Realizations

o Generic use case flow
o Example of Sequence for Login

 Implementation View
o Views

o Communicating between

Controllers
 Using of Rootscope

 PublishAndSubscribeService (

PubSubService)
o Client Routing

o InfraServices

o HTTP Interceptor

 Deployment View
Introduction
Purpose of this document
The SamWise Client Software Architecture Document (SAD) contains the architectural description
of SamWise system developed by National Institute of Health and Welfare. More detailed information
about SamWise server architecture can be found from document Server side architecture document. This
description consists of various architectural views of the client application. The client description follows
notation and structure of Server side architecture document. The description makes use of the well-known
4+1 view model.

The 4+1 view model enables various stakeholders (including system architects and developers) to
establish the impact of the chosen architecture from their own perspective. The Process View
(communication of processes) is not a separate chapter but can be found in the Use Case
Realizations and Deployment View chapters.

References
1. Samwise system architecture presentation
2. Server side architecture document.

Terms
Term Description
AngularJS Angular Java Script framework
.NET Application platform released by Microsoft
AOP Aspect Oriented Programming
ASP.NET Web platform based on .NET and released by Microsoft
BLC Business LogiC
JADE Jade templating engine. It is only intended to produce XML like documents (HTML)
 Cross Origin Request Policy is a mechanism that allows JavaScript on a web page to make
CORS
ajax requests between different domains.
Gerrit Web based code review system
Jenkins CI Open source continuous integration platform
Lims Laboratory information management system
REST Representational state transfer
THL National Institute of Health and Welfare

Document Overview
Chapter Stakeholder Description
Architectural
Software Architect Overview of architectural requirements
Requirements
Application's conceptual structure as a basis for technical
Use Case Realizations Developer
designs.
Implementation View Developer Application's technical structure.
System Way in which the application is deployed and (internal and
Deployment View
Administrator external) communication takes place.

Architectural requirements
This section describes the software requirements and objectives that have some significant impact on the
client architecture.

Non-functional requirements
Technical platform
SamWise client application is an AngularJS web application run in browser. For general AngularJS
architecture and architectural requirements see AngularJs documentation.

Design principle is to make the client as lightweight as possible. SamWise business logic and
functionality should be implemented in the SamWise server whenever possible.

Client-server communication
Client server communication is implemented in REST. Data format is JSON. HTTPS protocol is used.

Security
The system must be secure as operations will handle sensitive personal data.

The application must implement basic security behavior:

 Authentication: Users are authenticated based on authentication token.

As a result of login the client receives SamWise authentication token from server
  Authorization: according to their profile, users must be granted or denied permission to perform
some specific actions or viewing / editing some data.
Authorization is done on server. Server determines does the client have right to performed
selected operation. The task of the client is to clearly indicate to user which actions are
authorized and which are denied.

Layered architecture
SamWise client uses layered architecture in order to make modules and components to have as few
dependencies to each other as possible in java script environment. The layered architecture is explained
by the figure in the chapter Logical view.

Performance
All operations must be executed under two seconds. If operation lasts longer than two seconds, user
must be notified and given possibility to cancel the ongoing operation. Cancellation can be done by
pressing Cancel-button or corresponding user-friendly way.

Localization
The online service must be available in several languages (at least Finnish and English). The client view
must be able to support localization by using angular translate component. Other layers must be generic
enough to work with any internationalization context.

Logging
All client application logging is done via logging service. Separate logging service enables of receiving
from server logging level and instructions where to store logging files. The exact implementation of client
logging interface to server is defined separately by user requirements.

Local and/or cookie store in client

SamWise client uses cookie store or local store to store some basic user information like userId and
authentication token.

Storage is needed for persistence purposes..

Continuous Integration
SamWise system utilizes Jenkins CI environment and gerrit code review. In addition to that client side
modules shall have tests implemented. End to end test from user interface are not implemented at
development stage but will be introduced in smoke test level when the client has reached production
maturity.

Use Case View (functional requirements)

End user requirements are defined in SamWise Wiki. These are further divided into epics (that contain
use cases / stories) that are defined in THL's JIRA.
Logical View
Tiers
SamWise client is a layered web client. The client contains following layers

1. View
2. Controller (Ctrl)
3. SamWise service
4. Resource Service

Each layer elements may interface the elements in the same layer and elements in the below and above
layer.

The following diagram shows how SamWise client layers are connected.

View
HTML or compiled HTML page seen in the browser

Directive
Defines SamWise specific AngularJs HTML element. Directives may or may not be used. Directives are
used if and only if they provide benefit for the views.

Controller (Ctrl)
Controls the view.

Defines scope elements.

Does not implement business logic

SamWise service
Implements business logic.

Cannot contain any view specific user interface items.

Infrastructure Service
Defines commonly used infrastructure services like logging. Infrastructure service does not directly
implement any business logic.

Storage service
Defines Interface to SamWise client storages. The exact number of storages depends on business
document and is not defined in this document.

The following figure shows how Storage Service interfaces other services.
Resource Service:
Defines Resource that interfaces with web-server via JSON
Resource Service contains only the Resource interface without any business logic. It uses REST GET,
POST, PUT, DELETE or custom methods

ConstantService
ConstantService defines SamWise client constants that are readable by all layers of the client application.

Modules
This chapter gives an overview of SamWise client modules.

Modules on each layer are further divided into following components as in the SamWise server.

 Core: provides SamWise core functionality to other modules

 Sample management: provides sample management functionality
 Biobanking: provides biobanking functionality
 Lims: provides LIMS(Laboratory Information Management System) functionality

Use Case Realizations

This chapter gives generic overview from use case flow inside SamWise client. Chapter also presents
the architecturally significant use cases. For other uses please refer to SamWise technical wiki.

Generic use case flow

The figure below shows the generic sequence for use case flow inside SamWise client. Service,
Resource and Web Api requests are asynchronous and return promise.

From User to Server (1-5) and from Server to User (6-9)

1. User acts ( for example clicks a submit button on view)

2. View calls scope functions in the Controller
3. Controller calls SamWise Service that implements the business logic, a
4. SamWise Service calls Resource
5. Resource sends an asynchronous JSON request to the web-server
6. Web-server sends JSON Response to Resource
7. Resource solves the promise it has returned to SamWise service
8. SamWise Service solves the promise it has returned to Controller
9. Controller updates the View

Example of Sequence for Login

Before a user logs in SamWise displays only the login page to user.

Sequence:

1. User logs in by entering credentials and clicking Login-button.

2. View detects clicking of Login-button.
3. LoginController calls AuthenticationService.
4. AuthenticationService calls AuthenticationResource.
5. AuthenticationResource sends a request to the web-server
6. Web-server returns HTTP response to AuthenticationResource
7. AuthenticationResource solves the promise it has returned to the AuthenticationService
8. AuthenticationService stores the Authentication Token and solves the promise it has returned to
LoginController
9. LoginController updates the view

Implementation View
This chapter describes high level implementation patterns for SamWise client. Refer SamWise technical
wiki for more detailed information.

Views
SamWise client views are implemented as JADE files that are complied to HTML files. Compiling is done
automatically by the SamWise client development environment.

Communicating between Controllers

Communicating between controllers is done via SamWise services on PublishAndSubscribeService

Using of Rootscope
Angularjs rootscope is used only by PublishAndSubscribeService. It uses only rootscope broadcast
command. Rootscope does not contain any data.

PublishAndSubscribeService (PubSubService)
This service implements AngularJs broadcasting interface for SamWise client.

Basic usage:

 Controller that wants to share key PreparteForBroadcast

 Controllers listen to broadcast: Listen Broadcast

The following diagram show Publish and Subscribe user case: User logs in SamWise client

1. Login Controller prepares for broadcast key loggedIn ( it shares information that user has logged
in)
2. PublishAndSubscribeService broadcast the key. LayoutNavbar Controller listen broadcast event,
now it detects event
3. LayOutNavbar Controller reads key loggedIn from Publish and Subscribe Service
Client Routing
Application routes in Angular are declared via the routeProvider. It makes it easy to wire together
controllers, view templates, and the current URL location in the browser.

Routing includes parameters that define who can access the view:

 publicAccess everyone can access, if false only authenticated users may access
 projectAdministrator: only project administrators can access
 systemAdmininstrator: only system administrator can access
 If required routing can prevent user accessing views of for example Biobanking module

Routing defines rough basic mechanism to enable and disable views from users. It does not provide any
method to control what data user sees inside a view.

The following diagram shows the idea of the routing control preventing access to views that are closed to
public.
InfraServices
Commonly used infrastructure services include logger.

HTTP Interceptor
SamWise client implementation includes Interceptor. Interceptor main functionality is to log HTTP errors.
 Deployment View
SamWise client deployment is done as described in Server side architecture document. This document
does not describe client application deployment.

Client and server are always deployed at the same time.