System Design Specification
This document provides the overall design structure of our project, as well as how we plan to operate and test our product.
The Saros Framework (http://sarosoftware.com/products) is built drawing from the best of Zend Framework, CakePHP, and Symphony, but doesn’t have such a long history. This allows it to have important features implemented in a deliberate manner rather than as an afterthought with the evolution of popular technologies. Because of our team’s familiarity with this framework, we chose to use it for our project.
The Saros framework uses the standard model-view-controller (MVC) framework pattern. Controllers handle the requests which use models to deal with the data, which the controller then passes onto the views. The Saros Framework bases all modules off of a basic Controller class, which sets up the base of the framework. It is the heart of the framework and performs most of the redundant work that frameworks hope to prevent the user from having to do, such as autoloading libraries.
Additionally, Saros has a class called Spot. Spot is the Object-relational mapping (ORM) that the Saros Framework uses to connect to the database. For that to work smoothly, we have PHP classes that extend the \Spot\Entity base class that match the structure of our database tables (to be described shortly). Having Spot allows the different systems to not need to write plain SQL queries, which helps security, and abstraction such that we can handle relations and other logic in a centralized place to be utilized by other modules and subsystems.
GroupMatch requires a significant amount of data storage. Within our website, we will be storing the following information:
-
Username and password for poll creators / users with profiles
-
Poll questions
-
Categorical answers for polls determined by the poll creator
-
The names of the poll participants as well as the ratings for each of the categorical answers
As a result of the quantity of data we will be storing and in order to have efficient data lookups, we will be utilizing a MySQL database. In order for this system to work efficiently with large amounts of data, we will be storing it all in a database. The database table schemas are as follows:
-
Persons(id, pollId, name)
-
id: a unique identifier for a person that has answered a poll
-
pollId: an identifier for the poll that the participant responded to (Polls.id)
-
name: name of the person
-
-
Users(id, username, password)
-
id: a unique identifier for a person with a profile so that he/she can manage his/her polls
-
username: username of the of the poll creator to access his/her account
-
password: the password of the poll creator to access his/her account
-
-
Polls(id, userId, question)
-
id: a unique identifier for a poll
-
userId: the unique identifier corresponding the creator (Users.id)
-
question: the question being asked by the poll
-
-
Options(id, pollId, name, maxSize)
-
id: a unique identifier for a possible poll answer specified by the poll creator
-
pollId: an identifier for the poll that the answer corresponds to (Polls.id)
-
name: the text explaining what the possible answer is
-
maxSize: the maximum amount of people allowed to be categorized with this answer
-
-
Answers(id, personId, optionId, priority)
-
id: a unique identifier for an answer specified by a poll participant
-
personId: the id of the person that specified the answer (Persons.id)
-
optionId: the id of the option that the specified ranking corresponds to (Options.id)
-
priority: the rating that the user specified towards this option, like ⅘ stars
-
This database schema is also flexible to expansion: it can be easily modified to allow multiple questions to be involved in a poll. To do this a question id (questionId) must be added to the Polls table, and the pollId field in the Options and Answers table needs to be changed to a questionId field. Switching to this new schema would be an easy process: because all of the polls before the conversion are only associated with a single question, all of the questionId fields would simply need to be a copy of the pollId fields.
From the Controller class, we extend it to implement 3 basic controllers:
-
Index: a controller that displays pages and validates forms associated with the home page and registration page.
-
Account: a controller that displays pages and validates forms regarding user profiles and poll creation.
-
Poll: a controller that displays pages and validates forms associated with polls that have been created.
Each of these controllers will use the Auth module from the Saros Framework. It authenticates users using the Users entity class connected to the database. This action is performed before any of the basic functions (such as indexAction and registerAction) are performed, as defined by the default controller. Thus if a user is validly logged in or invalidly logged in, the actions associated with said login are performed before any form processing or any database information is manipulated. If the user is not valid, his/her invalid login is terminated and they are redirected to the homepage (Index/indexAction). Similarly, if the user is validly logged in, and they visit any of the functions in the indexController, they will be redirected to the Account/indexAction page.
The Index Controller will have 2 primary functions: indexAction and registerAction. The indexAction of the Controller is the default action of all controllers. This particular indexAction defines variables and information associated with our home page of our website, which will display a description of how to use our site as well as a login form (see UI diagrams in the SRS for a more accurate visual description of each of all of the pages). There will also be a “Register” button that will redirect to the registerAction of this controller. It loads the view associated with our home page. Because our homepage has a login form, this function also validates the form, if variables have been sent through a POST request (All forms on our website POST back to themselves because the framework makes this method of validation extremely simple). If the user provides correct information, they are logged in. If invalid information is supplied, the user will be redirected back to the form associated with the function and error messages will be displayed, as is the case for all form validation pages. Additionally it will redirect to the Account/indexAction if the user is validly logged in to our site.
The registerAction performs similar actions to indexAction except that it initializes the user registration page. The registerAction defines variables and information associated with our “Create a Profile” page of our website. It loads the view associated with said page. If variables have been sent through a POST request, this function also validates the form associated with the page. If the information is valid, a row will be inserted into the Users database table, using the Users class. Again, this function will redirect to the Account/indexAction if the user is validly logged in to our site.
The Account Controller will have 2 primary functions: indexAction and createAction. The indexAction defines variables and information associated with the user’s profile page of our website. It loads the view associated with the user’s profile page. This page does not have any forms, so form validation is not required. This page will show the question associated with each poll that the user has created, as well as a plain text URL for said poll (which he/she can use to distribute to participants). There will also be a “Create a Poll” button that will redirect to the createAction of this controller.
The createAction performs similar actions to the Index/registerAction except that it initializes the poll creation page. It validates the form associated with its view, which displays a form with a question to ask and allows users to add categorical answers to the poll on the fly. If the form is valid, a row is created in the Options database table for each answer, and a row is created in the Polls database for the question.
The Poll Controller will have 3 primary functions: indexAction, solutionAction, and addAction. Each of these actions has a single parameter, the poll id, which is a global unique identifier (GUID). It uses this GUID to query the database and gather the required poll information. If this GUID is invalid, it will redirect the user to either the homepage or the profile homepage, depending on whether the user is logged in or not.
The indexAction simply displays all of the information that each participant has provided in a table. This page also has a “Solution” and an “Add My Preferences” button, which redirects to the solutionAction and addAction of this controller, respectively.
The solutionAction uses all of the ratings and preferences provided by the poll users to find a way to “optimize happiness” of the users and best sort them into the groups associated with a category. It displays a visual representation of this information.
The addAction performs a similar operation to Account/createAction, except that the form and page the it displays is for adding preferences. Each possible preference, as defined by the creator, has a clickable star rating scale that the user can use to rate their preferences for the given category for a given poll question. The addAction validates the information associated with this page. If the form is valid, a row is inserted in the Persons table of the database to associate answers with a name, and a row is created in the Answers table for each preference provided.
In order to provide a better understanding of our system architecture, the following UML class and Sequence Diagrams have been created. The UML class diagram illustrates the controller structure described in the "Controllers and Views" section.
UML Class Diagram
In order to give a real example of how the controllers will operate with one another, the following use cases have been provided. Each flowchart shows actions by the user and how the system will respond. The associated UML Sequence Diagram shows how all of the classes/controllers in the UML Class Diagram will interact in each of these cases. As you can see from the images below, each controller is activated by either a link or button being clicked by the user. The controller then makes the necessary calls to the databases, manipulates the data from the queries, and then displays an HTML page using said data. This process repeats with different controllers and views until the action is completed.
Login Flowchart
UML Sequence Diagram - Login
Poll Response Flowchart
UML Sequence Diagram - Poll Response
We are utilizing PHP for our group matching search algorithm. Alternatively, we could use Java to solve our group matching problem. This alternative stems from the fact that PHP is an interpreted language, resulting in significantly reduced performance for complex algorithms and algorithms that have many a significant amount of function calls. Our optimal group matching algorithm requires extensive recursive backtracking in order to determine the best ways to group participants. Because of this, we are unsure of how well PHP will be able to handle large group matching problems. However, if we were to implement this algorithm in Java, we would have to determine how to properly connect this Java algorithm to our frontend using Apache Tomcat. This connection problem could easily consume large chunks of time. As a result of this major inconvenience, we decided to develop our search algorithm in PHP; if PHP does end up being too slow however, we will have to determine how to implement the search algorithm in Java and connect it to the front end using Apache Tomcat.
This section addresses the following topics:
-
Risk assessment
-
Project schedule
-
Team structure
-
Test plan
-
Documentation Plan
-
Coding style guidelines
This section describes the top five risks regarding this project.
- Change since SRS: We have gathered sufficient evidence to be concerned about possible performance issues of PHP.
- Likelihood of occurring: Medium
- Impact if it occurs: Medium
- Evidence upon which we base our estimates:
- Steps you are taking to reduce the likelihood or impact: We are developing our product in a modular and object oriented fashion with intelligent information hiding in the algorithm module to more easily port into Java if need be.
- Plan for detecting the problem: We will build benchmarking into the unit tests to not only ensure correct output, but also timely output for various sized input.
- Mitigation plan should it occur: We may have to use Java and Apache Tomcat to implement backend algorithm.
- Change since SRS: We have determined the exact command that needs to be executed on the MySQL server.
- Likelihood of occurring: Low
- Impact if it occurs: High
- Evidence upon which we base our estimates: Many webhosting companies block port 3306, to defend against security threats.
-
Steps you are taking to reduce the likelihood or impact: We need to see if we can run
GRANT ALL ON *.* to root@<ip-address> IDENTIFIED BY <root-password>;for each developer’s ip-address that needs MySQL access. - Plan for detecting the problem: This will be discoverable upon attempting the the above command.
- Mitigation plan should it occur: If we can’t gain individual remote access to the MySQL server we will need to assign a database lead that will be in charge of committing the teams DB changes.
- Change since SRS: Mitigation and likelihood reduction plans have been devised.
- Likelihood of occurring: Low
- Impact if it occurs: High
- Evidence upon which we base our estimates: We are programmers and the creators of the application. As a consequence, we will be biased in our assessment of our applications usability. We could create some feature or UI element that makes perfect sense to us, while completely confusing an average user.
- Steps you are taking to reduce the likelihood or impact: At the very least we will enlist the help from friends, family, and roommates to beta test our application. Ideally we will disperse a web form based beta test through a social network to obtain a large sample of test data.
- Plan for detecting the problem: A quick interview of potential beta testers will reveal whether this will develop into a large issue.
- Mitigation plan should it occur: If we can’t get enough users to test our app, we might beg/bribe our classmates to beta test for us.
- Likelihood of occurring: Medium/Low
- Impact if it occurs: High
- Evidence upon which we base our estimates: We’ve already dealt with some lack of communication issues so far in the project.
- Steps you are taking to reduce the likelihood or impact: We are taking a proactive approach to team communication: everyone has each other’s email and phone numbers. Nick has made a point of texting members who need extra encouragement to check in with progress reports.
- Plan for detecting the problem: This is a binary parameter. Either members of the team are communicating or aren’t.
- Mitigation plan should it occur: If communication falls apart so will our project. In an extreme case, team members who are left still working together will have to push on without the help of ones who stray.
- Likelihood of occurring: Medium
- Impact if it occurs: Medium
- Evidence upon which we base our estimates: Hayden and Vikram are two of the people responsible for the search algorithm, but they have no experience developing in PHP which could prove to be a hindrance on the production of the algorithm. Due to time spent learning the language an increased amount of time will be spent just getting the syntax correct.
- Steps you are taking to reduce the likelihood or impact: We are gathering tutorial and jump start information for members of the team who are unfamiliar with the environment of their assigned task in order to assist in a smooth development transitions.
- Plan for detecting the problem: We will set up a small and easy programming assignment to ensure that members who are developing in PHP know enough to begin development. Based on the results, the team should be informed to whether we will have an issue.
- Mitigation plan should it occur: If we can’t get members up to speed, we will have to shift responsibilities in order to better distribute the members skills and experiences.
This section describes the timeline in which we will complete various milestones regarding our project.
- This week was lost week due to project proposals and team assignments.
- Setup repository: Since most of the coding will be done in PHP we wanted to have some form of version control to facilitate work being done in parallel. This included both a repository system and periodic pushes to the actual server. This was setup by Eli and constituted about 1 day of work. This was a dependency before any of the other PHP work could progress.
- Make backend algorithm: An algorithm to generate a solution is essential to the project. This was generated in a brute force method so that we could have a starting point. This took Kyle about 1 day to complete.
- Backend unit tests: This was dependent upon the backend algorithm being complete, but we wanted to get the unit tests up in parallel. We didn't follow truly test driven development, but we wanted to have existing test cases so that it will be easy to show whether future algorithms are correct. This took about 2 days of work. It isn’t a direct dependency to future iterations, but it facilitates the work.
- Setup repository connection in eclipse: This was a task for every member and took about 1 day to setup. Again, this was a dependency for all future PHP work.
- Setup database schema: We need to maintain information about each user and information about each poll so that the values can be updated and displayed. The schema design was determined by the back end team and took about 1 days of conversation and 1 day of setup. This is required as a contract before any of the service call work could start.
- Build front end shell frame: All of the pages have at least some common attributes that are not unique to the user. For this reason we need a shell of the site with dummy links in the very least. These shells will be torn down and values will be re-injected depending on the user, but basic links and common display will remain. This will be handled by the Web UI group and should take about 4 working days to get a first usable shell up. This needs to be completed before work can start on page generation and injection.
- Hookup account generation and login: Given user information the system needs to verify, store, and authenticate user information. These hook-ins will be provided by the Profile and Poll group. The internal interface should take 5 working days. This must be completed before page injection and profile presentation can happen.
- Hook up poll creation: On request a poll needs to be generated and stored in our system. The front end form will be completed by the Web UI and this will take about 2 working days to complete. It is not a dependency for anything as we can use dummy data for testing.
- Generate second version of solving algorithm: This will entail a few white boarding sessions followed by a fairly small amount of coding to be completed by the back end team. This will take a total of about 4 working days.
- Hook up poll response: On request a poll response needs to be generated and stored in our system. The front end form will be completed by the Web UI group and should take about 3 working days. This is a dependency for the backend hookins to with the backend hookins to be completed by the Poll and Profile group by the be testable.
- Hook up page injection: Once we have basic shells we will need to hook-in injection of actual values. The maintenance and calls to get these values will be provided by the Profile and Poll group team and the Web UI group will actually link in the hookups. This should take about 5 working days
- Generate Unit tests for backend algorithm: We will mock out components to test the entire backend portion of the call. We will not be doing full Selenium testing as this is out of the scope.
- Hook up solution generation: Once a poll is generated, the backend algorithm needs to be linked with our UI for solution generation. Iterations of the algorithm are provided every two weeks, so it will be on the Web UI team to hook up the submission and presentation page. This is a slightly larger chunk and is dependent on the backend algorithm running efficiently. This should take 8 working days.
- Hook up poll creation and response: The front end poll creation form was created as a dummy in week five. With the shell in place it will be the responsibility of the Profile and Poll group to hook it up the the server and test that values are being updated properly. This should take 4 working days.
- End to end testing: Walk through use cases and be sure that functionality is working as expected. This will be on the web UI group and will primarily be manual. This should take two working days.
- Refine frontend shell: With all logic connected, we will do manual walkthroughs of all use cases a second time. In this, each member will generate suggestions and we will meet early in the week to decide final tweaks and changes.
- Generate final version of solving algorithm: Taking into account any latency issues or optimization ideas, the backend team will generate a final version of the solving algorithm and put fully mocked tests around the process. This should take 6 working days.
- Unforseen Issues: As with all projects, unforeseen issues come up and need extra resources and time to work on. We have allocated the last two weeks to tackle these issues. If we find that the changes at this point are minor we will start working through some of the stretch goals to generate a polished final product.
- Unforseen Issues: This will be the same as week 9.
The group is split into 3 categories: Profile and Poll Management, Database and Backend Algorithm, and Web Interface (Note: there is some overlap between teams). The Profile and Poll group is primarily responsible for creating the forms and submitting form data to the database. They are also responsible for managing logins, and making sure only the poll creator can access his polls and poll solutions. The Database and Backend Algorithm group is responsible for creating the database schema, managing the databases, and creating the optimal group-match search algorithm. The Web Interface group is responsible for implementing and extremely friendly user interface, as well as ensuring proper linking between the pages.
The Profile and Poll group will consist of the following teammates:
-
Nicholas Castorina
-
Kyle Zemek
-
Eli White
The Database and Backend Algorithm group will consist of the following teammates:
-
Hayden Jensen
-
Vikram Kudva
-
Kyle Zemek
The Web User Interface group will consist of the following teammates:
-
Justin Ryll
-
Nicholas Castorina
Nicholas Castorina will be the Project Manager (PM) of the group.
The whole group will meet to coordinate every Saturday at 1:00 PM for as long as necessary to come to an understanding of what needs to be done in the following week. Additional group meetings may be held via Skype conference call, or possibly in person, if deemed necessary. Aside from weekly meetings, most non-urgent communication will be done by group email. Weekly status reports, as well as other product descriptions and reports, can be accessed by all group members on the project wiki on github.
This section is intended to outline how tests will be formed, how frequently each type of tests will be performed, who will perform the tests, and how we will manage bugs and errors.
The unit tests will confirm that all controllers and functions work as intended. They are meant to ensure that the controllers perform properly, and that do not contain functionality that is meant to be encapsulated by another controller. As controllers are created, they will be tested by the person that built it before moving on to the next one. In other words, each team is responsible for unit testing their own controllers and functions. However, when black box testing is required, we will have group members outside of the team that created said function/module test it. Unit tests will be performed with the highest frequency. Several unit tests will be performed whenever a significant change is made to a method or module. For each function that is developed, at least two unit tests will be developed. We will be sure to include edge cases, exception points, and correct cases in these tests.
A system test will test that all modules and functions interact properly in all scenarios. The tests will most likely be performed by a member from each team. These tests will be performed on a biweekly basis, as the time it takes to make sure all teams are synchronized.
The usability tests will primarily be performed by the Web User Interface group to determine whether the user interface (UI) works as expected, and to ensure that the UI is intuitive for all users. Usability tests will be created to determine the optimal way to display information / provide feedback to the user, making it so that all possible actions are easily understood. This includes the best way to show errors to users when they incorrectly enter data into forms. As expected, this will require substantial user feedback and/or inter-team testing. For this we will primarily use our peers, but will occasionally use teachers of group project classes, for they will be able to provide the most insight (they are our a large portion of our target audience). The tests will be developed and run as the team creates pages, or updates existing functionality. The frequency of these changes hinges on the speed of the front-end UI team, as changes made will need to be tested.
The following test strategy is fairly comprehensive. As changes are made, the changes are tested, and the entire system is tested when major changes are made. However, bugs will arise from time to time. Consequently, we will use the Github issue tracker to track and manage bugs.
The user interface is intended to be self-discovered and intuitive. Thus each page will make it very simple to understand the possible actions one can take; there will be large buttons stating what actions can be taken, as well as a small amount of instructional text on each page. Additionally, the home page of the website will contain a description regarding the backstory and purpose of the site.
This following is a list of links to coding style guidlines that we will follow:
-
PHP: http://framework.zend.com/manual/en/coding-standard.coding-style.html
-
Javascript: http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml
-
HTML: http://www.peachpit.com/articles/article.aspx?p=24011&seqNum=3
Additionally, we will do code reviews to check for proper coding style on every repository commit.
[1] "Ubuntu: Intel® Q6600® One Core Computer Language Benchmarks Game." The Computer Language Benchmarks Game. Web. 19 Apr. 2012. http://shootout.alioth.debian.org/u32/benchmark.php?test=all.