WebCheckers Design Documentation

Team Information
• Team name: Team D
• Team members
– Brian Horch
– Other Member 1
– Other Member 2
– Other Member 3
– Other Member 4

Executive Summary
This document concerns itself with the high-level design of the WebCheckers project. As such, this document
contains complete information about how the project is designed and what architectural and other choices
were made. It first begins with a general summary of what the application is required to do. Then it discusses
domain-level discussions before going into each architectural layer in detail. The document then concludes
with the testing plan and current testing results.

Purpose
This product is being developed to teach its developers proper software writing procedures and processes. It
also exists to show how to write quality object-oriented code with design choices that make it easier to do
things such as testing and modification.

Glossary and Acronyms

Term Definition
MVP Minimum Viable Product
UI User Interface
VO Value Object

Requirements
This application must be able to:
• Allow users to sign in using a unique name
• Allow signed in users to sign out
• Allow two users to play a game of checkers using American rules
• Allow users to resign a game that they are in
• Allow users to ask for help from the computer during their turn
• Allow users to save and replay past games

Definition of MVP
The MVP will allow for people to sign in, play checkers with other signed in users, and sign out when they
are finished.

MVP Features
The MVP will have functionality to allow for a user to click on a link to sign in. Then they will be able to
enter a potential name. If the system finds that name invalid because it is either already taken or contains
invalid characters, then it will send them back to the sign in page to enter a different name. If the system
deems the name valid, then they are signed in and can now challenge and be challenged by other signed in

1
users. Once challenged or challenging they enter a game of checkers where they can make any valid move (as
deemed by the American rules) or resign when it is their turn. When it is not their turn then the user can do
nothing except resign. Once the game has been played to its conclusion or someone has resigned, a winner id
declared and both players are returned to the main lobby so they can play another game against each other
or other users.

Roadmap of Enhancements
The first enhancement allows for users to ask for help from the system itself. Once the user clicks the “Hint”
button then the system will provide a valid move for the user. This is only allowed during a user’s turn when
they have not inputted a move. If there are jump moves available, then the system will almost always pick
the one that leads to the most jumps. In the case of a tie, the system will arbitrarily decide one. If there are
no jump moves available, then the system will provide a random valid move.
The second enhancement saves games for users to replay later. Once a user opens an old game to replay it,
they will be taken to a replay mode where they can replay a game one move at a time. This allows for each
move in a multi-jump turn to be shown individually. If the user who opened the game was one of the players
in said game, then the board will be oriented in the same manner as it was when they were playing the game.

Application Domain
This section describes the application domain.

Figure 1: The WebCheckers Domain Model

This application is used to play checkers using the American rules. Each player can challange others to a
game of checkers. Such games are played on a board. The board is an 8x8 grid of spaces, each of which can
contain up to one piece. Players advance the game by taking turns. Each turn is comprised of one or more
moves of multiple different variaties. Each move involves moving one of the player’s pieces. The nature of
the move and the piece decide whether or not the move is valid. Once a valid move is made and the turn is
passed and the other player can take a turn. This continues until the game is over.

Architecture and Design

The application is a web application and therefore has two major segments. The first of which is the client-side
section. This section is comprised of the browser that renders sent http responses. The other section is the
server-side section. This section is where all the information is dealt with. It is split up into three components,

2
UI, Application, Model. The UI section controls what the client-side browser is supposed to display. This is
done through Spark route components and FreeMarker html templates. The application tier is where all
the logic happens. When there is a major state change within the server (i.e. two users enter a game) the
application tier handles the transition between the states and ensures that everything works as it is supposed
to. The model tier stores information for the UI and application tiers to utilize. It is mainly comprised of
value objects which hold specialized pieces of information.

Summary
The following Tiers/Layers model shows a high-level view of the webapp’s architecture.

Figure 2: The Tiers & Layers of the Architecture

As a web application, the user interacts with the system using a browser. The client-side of the UI is composed
of HTML pages with some minimal CSS for styling the page. There is also some JavaScript that has been
provided to the team by the architect.
The server-side tiers include the UI Tier that is composed of UI Controllers and Views. Controllers are built
using the Spark framework and View are built using the FreeMarker framework. The Application and Model
tiers are built using plain-old Java objects (POJOs).
Details of the components within these tiers are supplied below.

Overview of User Interface

This section describes the web interface flow; this is how the user views and interacts with the WebCheckers
application.

3
 Figure 3: The WebCheckers Web Interface Statechart

When the user first opens the application in their borowser, they are directed to the home page. From there
they can go to the sign-in page where they can then input a name. After a valid name has been inputed, the
application redirects them to the home page. From there the user can then either challenge another user
that is not in the game or sign out. If they choose the former, they will be redirected to a new game if the
challenge was successful or be redicrected back to home with an error message otherwise. If they choose the
latter, they will be signed out and will have to sign in again if they wish to play a game of checkers.

UI Tier
The UI tier has two major parts. The first is a series of FreeMarker templates that allow for the program to
generate webpages given specific information. The other part is a series of Spark Route components that are
used to handle various http requests. These routes handle either “GET” or “POST” requests. “GET” routes
gather information to be used in generating a webpage using a FreeMarker template. “POST” routes are
used to have other parts of the webapp do logic and do not use FreeMarker templates.
There are also additional classes that support the route components. These include a WebServer class that
assigns routes to request types and URLs. There are also three classes that take model data and format it in
a way that the other UI classes can handle. The first is an abstract BoardView class that provides basic
functionality and the ability for its subclasses to provide more specific detail. The other two classes extend
BoardView and are used for displaying active games and replays.

Application Tier
The application tier is a collection of classes that do the vast majority of the business logic for the application.
This tier is the smallest by the number of classes. Within this tier we have the classes responsible for handling
the user input and seeing if it represents a valid move. These two classes, MoveValidator and TurnProcessor,
form a controller that handles the flow of the game and enforces the American ruleset. There are also various
classes that handle lists of objects that are to be displayed in the webapp and the logic required for each of
them. In addition, there is a HelpProcessor class that also generates a move when requested. Finally, the
PlayerIcon class is responsible for handling player challenges and starting a game if all involved players can
be put in one.

Model Tier
The model tier has classes that are VOs with the occasional larger data structure. Such VOs include the likes
of Player, Move and Position, which all store specific information and are used by other classes to perform
business logic. The classes Board and Game represent larger data structures that hold important information

4
about the state of a game. As such, there are more complex methods that are used to better implement the
“Information Expert” principle.
In addition, there is a distinct package that contains VOs that are used in replays. Each class represents
an unique type of action that can happen in a game of checkers. All of these objects implement a common
interface, ReplayActionItem, to allow for proper abstraction when generating replays.

Design Improvements
For design improvements, there are a handful of things to do. For example, some classes have methods that
are no longer used. These methods should be removed, but have instead been forgotten. In addition, the
group was still learning object-oriented design principles and some of the classes made early on tend to have
certian design choices made that make it harder for them to be tested. Therefore, to fix this, the group should
identify problem classes and refactor them to make them easier to test. Finally, for the get help enhancement,
the algorithm used to determine the longest jump move can fail under very specific and rare circumstances.
This can be fixed by remaking the algorithm using a different approach, but the fix was not performed due to
a time constraint.
In the case of metrics there were only hot spots in the complexity metrics. Those metrics are shown below:

Figure 4: Complexity metrics for certain classes

These metrics show that the weighted method complexity for Board, Game, and MoveValidator are too
high. In the case of Board and Game, the classes have a bit of business logic in them to better follow the
information expert principle. However, the metrics suggust that we redo the more complex methods within
the class to be simpler and more efficient. In the case of MoveValidator, more work needs to be done. To
start, there are several methods that do similar tasks in searching certain spaces on the board and seeing if
they are occupied by pieces or not. This leads to a good bit of repetetive code. To fix that problem, we would
have to adapt certain methods to use helper methods to reduce repetition. In addition, the complexity of
MoveValidator made it hard to test, so refactoring it to make it simpler would also make testing it far easier.

Testing
For this project, we did two types of testing, acceptance testing and unit testing. The specifics about how we
did each mehtod and the results are outlined below:

5
Acceptance Testing
To do acceptance testing, we went through each story’s acceptance criteria and checked to see if they could be
fulfilled. Since the project is complete and all functionality has been implemented, all stories have been tested
completely and pass all of their accpetance criteria. In additon, before submitting the project, we made sure
to do retrograde testing to ensure that we did not accidently breake previously implemented functionality.
Since we made sure there we did not break any old functionality when implementing new functionality, there
were no problems during retrograde testing. Overall, acceptance testing went smoothly.

Unit Testing and Code Coverage

In the case of unit testing, we had varying stratagies based on what type of object we were testing. For
example, when we were testing VOs, we went method by method to ensure that the class under test would
output the expected results. However, for classes such as Spark route components, we needed to be more
thorough. This involved using mocks to isolate the class from its dependencies and to better simulate certain
conditions. Then we had each test method handle a different scenario. Some routes only needed one test, but
for more complex ones we needed several to properly test all possibilities.
Our final code coverage report is shown below:

Figure 5: Final code coverage report

Our code coverage was not as high as we had hoped. This is mainly due to the time constraints that we had.
We made a decision to do unit testing after functionality was created to ensure that we did not loose points
on the highly-weighted functionality section of the sprint grade. After we had finished this, we set a hard
target of 50% coverage and a softer target of “as high as we can get it.” We were able to reach our 50% goal,
but we were unfortunatly not able to go past it.