Illini Spatio - University of Illinois - Engineering Wiki

yrekazzyzxamuckInternet and Web Development

Dec 4, 2013 (4 years and 9 months ago)


Illini Spatio
Project Documentation

Space Avengers
Yuk Yin Maurice Lam
Wei Chen
Shogo Kimura
Shengchao Huangfu
Litin Chowdary Tripuraneni
Smit Shah
Joshua Harris
Jordan Arrieta
Gurneet Sandhu

This documentation contains a system overview and all relevant technical details of
. This is designed to be a reference materials, which means you should read the first
couple pages to get an idea of the project, and then go through the code, and then refer to the
documentation to look for something. Therefore, this document is designed to augment the
code and comments, not replacing them. Please refer to both of them when trying to
understand the project.
The most useful reference materials are
REST API documentation
if you are reverse engineering.
System Architecture
Interface Design
will give you in-depth
understanding of the philosophy of our software.
UML class diagrams
sequence diagrams
will also give you an overview of the
project in a visual way.
The Appendix contains
Installation Instructions
that has step-by-step instructions to set
up the project in a fresh Amazon EC2 instance.
29 April, 2013

Table of Contents
Table of Contents
Development process
Goal / Project Overview
Interface design
Object format
Technology Stack
Coding style
Class diagrams
Sequence diagrams
Code components
Build process
Generated API docs
Technology Stack
Class diagrams
Code components
Future Plans
Personal Reflections:
Frontend setup
Backend setup

Development process
Our team follows a modified version of Extreme Programming (XP) software development
process. This process composes of three main parts. The first part is test driven programming,
where a software developer will write test cases first before starting to develop the actual
implementation. The second part is pair programming, in which two programmers will work
together on the same piece of code. This means one programmer will do the actual coding,
while the other programmer catches mistakes, write additional tests and write
documentation. The third part is refactoring. Refactoring refers to the “
disciplined technique
for restructuring an existing body of code, altering its internal structure without changing its
external behavior
." Through refactoring, XP encourages the developer to first focus on getting
a feature to work, and only after then make the code readable and maintainable through
refactoring. One modification we made to XP is instead of doing pair programming by having
two programmers physically in the same room, we create change logs and send them to
another programmer for review.

Goal / Project Overview
Create a website with which a user can search a study space in UIUC based on his/her
preferences. A user can then filter our database of study spaces on campus by approximate
area, date and time range, availability of food or drink, silent or chatter, availability of
resources such as computer and books, etc. Our project allows students to find the most ideal
study space at any time of the day, and it is better than just going to places that they usually
We thought this project must be very interesting and helpful for students enrolled in UIUC
because students can use our project to find places they can go for studying based on their
preferences. For example, some students want to study with coffee, other students need to
study where computers are provided, etc. Furthermore, sometimes students want to study at a
silent place to study before exams, but other times they may want a place in which they can
talk when they need to discuss their team projects. Many students find their favorite study
spaces accidentally or through their friends, but it is kind of a big loss that they do not know
that there are much better places or simply more options from which they can use. We also
want such a tool for ourselves, so we believe it is good to be chosen as our project throughout
this semester.
Use Cases

When a user accesses the top page, he/she can see a campus map and a study space

A user sees a list of study spaces including their locations, which are also displayed on a
map with detailed space information. User may select a study space based on the
information provided.

A user can see small images right beside each item on the study space list so that they
can get general idea of how each space looks like.

When a user chooses a study spot, the website will show detailed information of the

study space (open hours, available properties, etc.)

Each study spot is shown as a marker on Google Map.

If a user zooms out Google Map, markers on the same building will be gathered up
together. When a user clicks the marker, a small bubble shows up and the user can
select one specific spot.

When a user clicks a button on the bottom right corner on Google Map , the center
location of Google map will be back to user's current location.

When a user clicks "Show in map" button in a study spot detail page, the map will
focus on the selected spot.

If a user zooms in Google Map enough, each study spot on the same building will be
separately shown up.

When a user types a query on a search bar, search result is dynamically shown as an

When a user inputs a query on a search bar, the system will filter the database and
give back a result list of study spaces.

When a user types specific words about properties of study spots on a search bar, a
user can filter our database by his/her preferences (open hours, noise level, availability
of technology, etc.).

When a user chooses a study spot from a list, photos will show up with detailed
information. A user can select photos will as if they are on a carousel.

When users or librarians find errors or wrong descriptions on the website, they can
report problems through a contact form.

An admin can login to admin interface and make changes on database. He/she can
add, remove, and modify study space information. Also, an admin can add/remove

An admin can add a new admin account. Also, an admin can remove an account.

At the fundamental level, our application is divided into the front-end and back-end. In a
nutshell, the front-end component is responsible for displaying the information to the user
while the back-end is responsible for storing the data. Since the two components use
completely different technology stacks, there is a very well defined division of labor between
the two. The two components communicate through a
, which means that the
front end will access and change data stored in the back end by visiting a URL.
On the front end, since we are using
Angular JS
, we follow the
Angular way
. The Angular
way divides the application into
, which are logical units. Further down each module
is divided into functional components. A
is a component that deals with interface
manipulations and other visual components. A
is a component which deals with
the business logic. It parses and translates the data fetched from the database into a form that
is readily usable by the views. A
is a HTML declaration of the specific presentation of
data into directives and other visual elements. The fourth type of component is
which are simply reusable segments of code that are general enough that can be used across
even different software applications. An example is the
service, which provides the user's
current location to the application. In some sense it encapsulates commonly used code into a
nice, reusable package.
On the back end, we use
. Django uses a model-view-template programming pattern.
It is similar to the well-known model-view-controller pattern, except that you call views
“templates” and call controllers “views”. Using the Django terminology, a view decides what
data goes into which template while templates control the presentation of the data. However,
as our backend communicates primarily through the RESTful API, there is not much
freedom for the presentation. So instead of making templates, we created serializers for our
models. Serializers are a core concept to the
Django REST framework
. Serializers turn
information in the database into the text representation which is then passed to the RESTful
API. This allows us to easily specify which data goes to the front end and which data stays
private. By following the model-view-serializer pattern, we were able to create RESTful APIs
very easily and concisely.

Interface design
Illini Spatio
is an information access tool, in that the primary goal of
is to provide easily
accessible information about study spaces on campus. Therefore the philosophy for our user
interface design is to eliminate all barriers between users and the information they want to
access. We want the users to be able to get the information as easily and effectively as
possible. We think the two major use cases of
, so in
designing the user interface, we optimized for these two tasks as much as possible.
Users may use
new study spaces. Imagine the scenario where a user’s
favorite study space is fully occupied and he wants to find another place to study. He would
want to discover new study spaces nearby. That is why we put the map front and center in the
interface, together with a list of study spaces in the area. We also provided the user with a
“locate-me” button that will show their current location on the map. This way the user can

quickly and easily see a list of study spaces near him and pick the ones he likes.
Users can also see details of a particular study space by clicking on a marker on the map or an
item in the list. In this view they will be able to see the facilities provided there and the
opening hours of that space. The main component of the detail window is the photo carousel,
which the user can easily flip through and see photos of the study space. We believe this is the
primary way in which users choose their study spaces. Moreover, the user can easily
recognize, through the pictures, whether they have been to that place before.
The other use case scenario is information retrieval, in which the user knows exactly which
study space they want to find, but want to check, for instance, the opening hours. That is
exactly why we have a search box that is always in the user interface. Users can simply type
in the name or relevant information into the search box and find a study space. The list of
spaces will automatically be filtered with the search term entered. The user will then be able to
see relevant results at a glance.

The front end and the back end communicates through a RESTful API. The following is a list
of supported REST endpoints to our backend server, and a sample response object.
GET /studyspot/
<spot[]> A list of all study
GET /studyspot/<id>
<int> id - The id for the spot
to retrieve
<spot> A study spot object
GET /attributes/
<string[]> A list of all
available keys for attributes
GET /features/
<string[]> A list of all
available features
POST /sendreport/
<String> userName
name of the user
Data in form encoded
<String> location
the location related to the
<String> description
description of the problem
<String> email (optional)
Email address of the user

Object format
Study spot




"Second Floor"



// Should be things like "Library", "Cafe", "Dorm" etc






"ACES Library"




// address is currently not used or displayed anywhere


"1101 South Goodwin Avenue Urbana IL"


"Second Floor"



// A list of image URLs. Usable directly by appending to the server host.




// A list of strings indicating what is available in this spot.

"Comfortable Seating"

"Air conditioned"




// Key value pair for displaying in the details pane






"Fully accessible. Except when it's not."

// Currently supported types are "Text" and "URL"



// Metadata for extensibility. This tag will be interpreted as a JSON
// string on the front end








// Open midnight until 5 am and 6 am until 10pm















... (and the rest of the week) ...





Technology Stack
Angular JS
The main web framework.
DOM manipulation library. jQuery is used
by Angular JS, and most use of jQuery
should happen inside a directive.
Javascript task runner, like
scripts. See
Build Process
Package manager for Javascript. Manages
the Javascript components inside
SCSS + compass
CSS precompiler and authoring framework.
Provides better CSS structures, like
variables, mixins and others.
Stylesheet for scaffolding. Provides HTML
classes for positioning and consistent styles.
A workflow tool that generates boilerplate
templates for HTML, JS, CSS, Grunt and

Coding style
We follow the JSHint (
) style of coding. JSHint is a linting tool
derived from JSLint, minus all the weird suggestions from Douglas Crockford (while retaining
all the good ones). JSHint catches stylistic problems like indentation errors, missing
semicolons and camelcase variable naming etc, but perhaps more useful is that it catches
dangerous, but valid, code blocks like the use of eval, with, type coercion comparison etc.
To facilitate the linting process, we setup linting in two places. First we individually set up
SublimeLinter (
) in our Sublime Text editors
so that it automatically highlights all problems as soon as we save. This has to be done on
each of our programmers development environment. In addition to that, we set it as part of
our code building process, so whenever you run grunt build, it will pass the code through
JSHint to check for any errors. This is set up through the version controlled grunt files and
npm package managers.

Class diagrams


Sequence diagrams


Code components
AspectRatio - A code that watches the width of a specific element and changes its height
accordingly. This is useful in responsive design where you want to maintain the aspect
ratio of something.
Detail - Controls the detail pane of the web page. Responsible for showing details from a
specific page.
DetailItem - Formats a detail item from its JSON representation to the user readable form.
Filter - Controls the search box on the top right of the page.
LocateMeBtn - Add on to
to add a locate me button to the map.
MapInfoWindow - Used in conjunction with map-markers to define the info window format
when clicked on specific markers.
MapMarkers - A directive to use in conjunction with the Angular-UI ui-map directive.
Automatically syncs with the given markers array.
Pager - Provides a similar functionality to UINavigationController in iOS SDK. Gives the
element ability to push new elements passed in and replace the current page.
Geo - An Angular service that updates with the current geolocation. This is a singleton object
so data calls from different clients will update the "global" location object.
Token - Filters a list of study spaces by the search token and the query.
Markers - A filter that groups spaces by their building if needed.
MainController - The main controller for the default page of the app. Glues other components

Build process
We use Grunt JS as our task runner. If you have never used it before,
you can think of it as a version of make, or as the JavaScript version of
bash scripts. It allows us to define tasks, or macros, so that they can be
run frequently.
To install grunt from the command line, use npm. The process is detailed here
List of useful grunt commands set up in our project,
grunt server 
- This creates a server in port 9000 to serve the front-end project. Very
useful for development and it reloads as any of the script files changes.
grunt doc 
- Generates the documentation as JSDoc of the system.
grunt test 
- Runs the unit tests. See the test section below for more details.
grunt e2e 
- Runs the end-to-end tests. See the test section below for more details.
grunt build 
- Builds the whole system. This will run the system through all necessary tests
and then generate a production ready version in the
grunt ­­help 
- Show a list of all commands available. Not all of them are useful as grunt
by default exposes all internal commands.

Angular JS has two types of tests: unit tests and end to end tests.
Unit tests
Unit testing aims to test one single method or one single piece of functionality each time. And
we are very strict about this. For example test should not try to instantiate a directive from the
HTML because it mixes the initialization with the execute of the method. Instead, we put each
directive's controller into a separate global object, so that we can truly test function by
function, method by method.
The grunt command to do unit testing is
grunt test
. By default it starts a new instance of
Chrome (which should be installed on your system) and run the tests in that instance. It will
then report the results in the terminal window. Configurations for the unit test can be found
End to End tests
End-to-end tests are integration tests that tests from the users perspective. It executes
commands from the user's perspective, like a click, keypress or input into a search box. It then
checks for things like visibility of elements, text contents of a particular text field etc.
The grunt command to do end to end testing is
grunt e2e
. Alternatively you can run
to create an instance of Chrome that will not close by itself, and watch for changes
and re-runs the test. This is useful for debugging the tests. End-to-end tests are set up so that
it runs on the built version of the app, which means it will also catch errors introduced during
the build process. Moreover, that means changes to the system will not be tested by e2e until
the system is built. Configurations can be found in

Both type of tests has a syntax that is derived from Jasmine. For more information, please
visit the link above.
Testacular / Karma
The tests are run by a test runner which used to be called Testacular. For some
, the runner changed its name to Karma. For the most part, this runner will run
transparently and you won't realize that it is even there. But what it is responsible for doing is
starting Chrome (or other browsers), pulling in the required files and tell the test framework
to start.
Test coverage
The grunt file is set up to automatically generate coverage results about our tests. The output
is an HTML file found in
app/coverage/unit/[Browser name]/index.html
. Note
that test coverage for e2e testing is known to be inaccurate because of the way it is run. So
take it simply as a guidance and proceed with caution.

Generated API docs
As mentioned in the
Build Process
above, we have set up an automatic process to
generate API documentations from code
comments. We are using JSDoc
) for this purpose.
However, since some of the Angular constructs are not so compatible with JSDoc
auto-detection features, we have to include annotations to make sure JSDoc picks them up.
For instance, any directive, service, filter or controller should be shown as a
, and
therefore should have the
annotation. Moreover, in most cases JSDoc would not be
able to pick up the methods of that Angular component (for example a function of a scope as
a method of the controller), therefore each
has to be annotated with
@memberOf myController
As mentioned, to generate the documentation, simply run
grunt doc
. This will create or
update the documentation in the
folder. The output format is HTML, and can be viewed
from any web browser.


Technology Stack
The main python backend framework.
Django REST
Framework built on top of Django for
creating REST APIs.
A much better looking template for
Django admin interface.
Schema migration system. Updates the
schema with minimal damage to existing
data when the model has changed.
Django CORS
Middleware for Django to add
related headers.

Class diagrams
This is the sequence diagram for the API. It is used in many different user stories as it is main
way to retireve any data from database. For example:
A user sees a list of study spaces including their locations, which are also displayed on a map
with detailed space information. User may select a study space based on the information

Code components
Serializers - It transmits the data structures and objects such as features into a format that
can be properly processed by the front-end and proceed accordingly.
InitDB - Initializes database from models
Models - Generates different models for the database. There are six different main models.
Such as:
Location: which is a general location of a set of study spots.
Open Hours: Open hours for a location.
Features: Feature list that is attached to each location.
Attribute: Generality feature for the admin to add new attributes without changing the
StudySpot: It is for the individual study spots around the campus..
SpotImage: Contains the information regarding the image of study spot.
Admin: It sets the permissions for the admin.
URL: Defines the URL patterns for the study spot information.
Views: Generates different views and returns list or individual locations.
Widgets: It is a widget for the input of the latitude and longitude with the Google Maps.

Testing our API:
We can now access our API, both from the command-line, using tools like curl.
Most of the backend testing is done using the built in Django test services. The majority of the
testing is done on the Django views. The Django test service, when run, creates a new
temporary database to which the test code is executed upon. The test service can also allow us
to mock sending requests to the views and checking the response. With it we can test the API
by submitting requests to Django and checking if the page is returned properly with all the
correct information. Tests are run by typingt he command: python test
The model of the database can be tested via the Django test service by execution operations on
objects represented by the model. Additionally, Django upon creating the database validates
the Models to check for any errors in the model configuration.

Future Plans
We are currently discussing with our client, the University Library, to host the application on
their servers and they will deploy the software to all students on campus. Depending on
further discussions with the library and the success of the project, we may continue
development of the project.
In the current version, the primary goal of searching for study spots in libraries all over UIUC
has been achieved. In addition to that, we have built an extensible system that can be
generalized easily to be used on other campuses. In the future, the University Library could
ask another team to add new features like a user login system and commenting system to this
Application. As a campus-wide project, there are a lot of work to be done data-wise: besides
libraries, information on other study spaces such as the Illini Union, open spaces in campus
buildings, and student dorms will have to be collected. Moreover, it would also be nice to
integrate directly with reservation systems of library study spaces so that users can use the
application not only for searching study spots but also for reserving a study room. Users also
can see current availabilities and conditions of each study space with the information updated
We hope the application will be popular among UI students and be proven very useful.

Personal Reflections
Maurice Lam
This is a great project that allowed us to venture into the cutting edges of web development.
We used relatively new frameworks, libraries and tools, like Angular JS, Yeoman, Grunt etc.
Using new stuff is not always fun, though. A lot of these new tools lack proper documentation
and support, and the compatibility with other libraries are also not guaranteed. A lot of times
halfway through the project we end up fixing bugs or creating workarounds for the libraries
we use. Anyway, it was a great project, and I am grateful to have these team members who
are willing to learn these new stuff with me.
Wei Chen
At the very beginning I couldn’t imagine myself be in such a large group working on such a
large scale application. However now looking back, I would definitely say it’s a precious
experience that we can never get anywhere else. We chose to do it the “hard way” by
challenging ourselves with all those exciting new web technologies, which were not taught in
any courses. It really did reformed the way I looked at web applications. It was also nice to
have the chance to work with real customers. Most importantly, this could never be possible
without everyone’s dedication and devotion into this project.
Shogo Kimura
Through this project, I have learned a lot. We decided to use a lot of new technologies which
we were not familiar with at first such as AngularJS, Yeoman, Bootstrap, etc. In fact, this
project was a big challenge for me, but I am glad that the project is finally achieved. I am
really grateful to such great team members; they are all helpful and skillful. Also, it was the
first time for me to work with clients/customers. We frequently contacted to customers and
had meetings to make sure our working progress and their requirements. It was a really good
experience, and I am sure that this experience will be helpful once I get into the society for
work. Many thanks to the project, the course, and the team members!

Shengchao Huangfu
I got a very good experience from this project. We used a lot of new technology like
AngularJS, Yeoman, Twitterbootstrap to develop our project. I have learned a lot about
Angular framework and skills to set up a good environment for the front-end development.
Our team was very good, and I really enjoyed working with my teammates. They helped and
taught me a lot. Additionally, we had several meetings with our customers. This was the first
time for me to work with real customers, which would be an important experience in my
future. Anyway, really thanks to my great teammates.
Litin Chowdary Tripuraneni
By far, this is one of the best experiences I had in computer science courses. Coming from
electrical engineering, I was lacking the coding skills which are needed for a computer science
student. This project helped me in overcoming this problem. I was able to learn AngularJS,
Yeoman, Bootstrap and many web development skills. Even though my contribution to the
project code was not satisfactory due to lack of my programming skills, I was able to learn
many new things and work with really cool people. My group members helped me a lot
throughout the project and we had lots of fun through out the weekly meetings. Now, I am
pretty confident that I can work in group projects efficiently and elegantly with this
experience. I sincerely thank all my group members and course staff for this wonderful
Smit Shah
This is one of the largest group project I have worked on in Computer Science. I really
learned a lot about how to collaborate and integrate various components from each members.
I also learned about backend technologies such Django, REST framework and others. For this
project, I collaborated with different group members and learned how to work together. I
really enjoyed the whole process of how everything came back together form backend to
frontend development and worked in unison. I would like to express my gratitude towards my
team members and Caius Brindescu who have always been helpful to me throughout the
project and made it more fun and enjoyable.

Joshua Harris
This project was a great experience. I learned a lot of new skills such as the Django
framework, I got to practice working with a RESTful API implementation, and worked on
making an email service. I enjoyed the challenge that came from learning about all these new
ideas and it helped to make me a much better developer. Additionally our team had a lot of
great front end developers. And while I got limited exposure to it, I still managed to learn a lot
about design principles. Additionally working in a team of 9 really forced us to have to
communicate unlike any other class project before. While it put us all out of our comfort zone
once in awhile it made us all stronger in the end.
Jordan Arrieta
Working on this project allowed me to further develop my coding skills. I learned new
material such as working with Django. This also was the first time I worked in a group of 8+
people (our group had nine!). It was definitely hard to work together efficiently at first, but
now as I look back, I can see we worked very well as a team and were able to accomplish our
goals. Communication was essential and I feel that our team managed accordingly. I learned
a lot, but also had fun with my team and this project!
Gurneet Sandhu
This project helped me learn the basics of Django in more detail. I worked with Django and
Python before but I never implemented the REST framework. This was the first time I
worked in a large team and I learned a lot about my strengths and weaknesses from the
experience. I will certainly use this experience in the future to work on bigger projects. My
group mates did a lot of stuff where I wasn’t sure. It was definitely an enriching experience.


The following instructions are configuration steps for a fresh Amazon EC2 instance. For most
cases the steps will be the same on other Linux systems. More specifically we were setting this
up in a Ubuntu environment.
First we have to set up the server with the basic server setup, including Apache, MySQL,
Python and Python-Pip.
sudo apt­get install git apache2 mysql­server mysql­client python­pip
Then we have to get a copy of the code from the github repo. Note that the repo is currently
private. To request access, please contact a team member.
git clone­avengers
git checkout deploy
Frontend setup
Deploy Installation
First set up apache to serve the files from the built system with the following steps. For more
on Apache documentation, see
Depending on different operating systems, please open corresponding config file to modify
or create new
and point to:

Development Installation
In order to support development, you would have to install the following additional libraries.
First install
. Note that we explicitly require an older version of node.js because grunt
is not compatible with the newer version yet (as of the time of writing).
sudo apt­get install npm
git clone
git checkout v0.8.15
sudo make install
Then install the tools that we use with front-end development: namely,
sudo npm install ­g yo grunt­cli bower
Then install
, and
, which are required for compiling SASS (or SCSS) files.
tar ­xzvf rubygems­2.0.3.tgz
sudo apt­get install ruby
sudo ruby setup.rb
To make Node.js packages work in the frontend module:
cd space­avengers/web/
sudo npm install
Finally you can do a grunt build to check that the system is working.

grunt build
To start a temporary testing server for development, use
grunt server
Backend setup
First install
and the relevant packages. Namely
. We
also need to install MySQL clients and the Python connectors.
sudo easy_install ­U distribute
sudo pip install django south djangorestframework django­grappelli
sudo apt­get install libmysqlclient­dev python­mysqldb
sudo aptitude install libapache2­mod­wsgi
for database setup
Finally run syncdb to setup the database schema
python syncdb
Creating new virtual server
For testing purposes, you can run
 python runserver
. But in a production
environment, you should run it in a more robust server package like Apache. The steps below
will go through how to setup a basic virtual host for Spatio.
First, create a new virtual host in Apache configurations, a sample virtual host definition may
look like this:

<VirtualHost *:8080>
        ServerAdmin webmaster@localhost
        DocumentRoot /PATH_TO_INSTALLATION/space­avengers
        WSGIScriptAlias /
        <Directory />
                Options FollowSymLinks
                AllowOverride None
        ScriptAlias /cgi­bin/ /usr/lib/cgi­bin/
        <Directory "/usr/lib/cgi­bin">
                AllowOverride None
                Options +ExecCGI ­MultiViews +SymLinksIfOwnerMatch
                Order allow,deny
                Allow from all
        ErrorLog ${APACHE_LOG_DIR}/error.log
        # Possible values include: debug, info, notice, warn, error,
        # alert, emerg.
        LogLevel warn
        CustomLog ${APACHE_LOG_DIR}/access.log combined
which will redirect all
the http requests.

import os
import sys
path = '/PATH_TO_INSTALLATION/space­avengers'
if path not in sys.path:
os.environ['DJANGO_SETTINGS_MODULE'] = 'space_avengers.settings'
import django.core.handlers.wsgi
application = django.core.handlers.wsgi.WSGIHandler()
Restart Apache server to see it work.
sudo service apache2 restart
Please note that if you wish to run frontend and backend on the same server, you might need
to run them on different ports. We would recommend running front end on Apache with port
80 and back end on Apache with other customized port.
to backend url
After the installation, simply navigate to the URL of the host to start using the app. No
additional requirements are needed to start using.