Office space finding with Freespace

Freespace is a mobile ready web application that allows the user, a corporate executive, to look for a room for a business meeting nearby. Available rooms in available buildings nearby are shown along with the floor plan of the building.

There is only one user for the web app, i.e. the executive who wants to look for a room for a meeting.

1. On starting the app, the executive is shown the registration page.
   
   
2. The executive needs to enter his/her name and email address.
   
   
   1. The name must be entered in English and Latin characters. Languages in non-Roman script such as Hindi are not allowed in the first version. The minimum length of the name is 2 and the maximum length is 64.
      
      
   2. The email address is usually a corporate one and is not usually GMail, MSN or AOL. It is most likely based on the domain of the company and is powered by Microsoft Office 365 or Google for Work. However, no single sign-on with such services is provided for in the first version.
      
      
3. After entering the name and email address, the executive submits the form.
   
   
4. The web app communicates with the server API to register the new user.
   
   
5. The server processes the request and returns a response to the app.
   
   
   1. The response can be a failure. The registration was unsuccessful for some reason and the server rejects the registration along with a reason. This reason is shown by the web app to the executive on the registration page itself.
      OR
      
      
   2. The response is a success.
      
      
      1. The server has created a new executive in its database.
         
         
      2. A new token called the confirmation token has been generated for this executive. This token will be used during the confirmation step. The token will be part of the URL inside the email which is sent to the user.
         
         
      3. The server has mailed the executive a registration confirmation email with a confirmation URL. This URL contains the token described in the previous step.
         
         
      4. On the web app, the executive is taken to a page where he/she is asked to check his/her email address for the confirmation email. No further action is possible on this screen.
         
         
6. Assuming success in the previous step, the executive has received the confirmation email for his/her registration. The executive clicks on the confirmation link inside the email.
   
   
7. When the confirmation URL with the token is hit, the server verifies that the token is valid.
   1. An invalid token leads to failure and the executive is told to check if the URL in the browser matches the one in the confirmation mail exactly and that no tampering was done by mistake.
      
      
   2. The confirmation token is immediately discarded and a new provisional session token is created for the next step.
      
      
8. Assuming success in the confirmation step, The server returns the provisional session token to the browser. This token identifies the newly registered and confirmed user.
   
   
9. The executive is taken to a page where he/she will choose a new password. The page has two text inputs, one for the password and another to repeat the password.
   
   
   1. The password can have any character available on an English keyboard layout. The minimum length of the password must be 6 and the maximum length 16.
      
      
   2. The password in the two input boxes must be the same.
10. The executive submits the form and the password is sent to the server. Along with the password, the provisional session token is also sent to the server to help the server identify whose password is being set.
11. On receiving the password, the server does the following
    1. Saves the password in the record for the user. The password is stored in an encrypted form.
    2. Immediately discards the provisional session token.
12. The executive is then taken to the login page where he/she can login to use the services of Freespace as a registed user.

1. On the login page, the executive needs to enter his/her email and the password. After entry, the form is submitted. The validity of the above entries is checked as per the rules described in the registration workflow.
   
   
2. The server verifies the user name and password based on the data stored in the registration workflow.
   
   
   1. If the username used by the executive is not part of the system, then the server returns an appropriate failure code. Using this code, the web app can show an error message which also helpfully includes a link to the registration page and a message that reminds the executive to register first.
      
      
   2. If the username is correct, but the password is wrong, then the server the returns an appropriate failure code. The web app can show a message which guides the executive to use the 'Forgot Password' link to generate a new one.
   3. If the credentials are correct, then the server generates a new regular session token for the executive. In all further communication between the browser and the server, this session token MUST be used to identify, authenticate and authorise every request from the user.
3. Assuming success from the previous step, the web app stores the newly received session token as part of cookies / web local storage of the browser. For all further requests specific to this executive, the web app MUST pass this token in all requests.
4. The executive is taken to the home page of the web app.

1. The executive clicks on a link named 'Forgot Password'. This is usually on the login page.
2. The executive is taken to a page where he/she is required to enter his/her email address.
3. The executive enters the email ID subject to the validation rules of email addresses.
4. The form is submitted.
5. The server checks if the submitted email address is part of the system.
   
   
   1. If the email address is not registered, then the server returns an error indicating an unregistered user. The web app can use the error to remind the user to register.
   2. If the email address is found,
      
      
      1. The server creates a provisional session token that allows the executive to generate a new password.
      2. An email is sent to the executive's address with a URL that takes the executive to the password generation page. The URL contains the provisional session token.
      3. Meanwhile, the executive is directed to a page that prompts him/her to check his/her email. No further actions are available on the page.
         
         
6. When the executive clicks on the URL in the email, further workflow is the same as steps 9 to 12 of the registration workflow.
   
   

1. After login, the executive is taken to the home page.
2. While loading the home page, the web app requests for the list of buildings nearby.
   
   
   1. The request must contain the regular session token to indicate the executive logged in right now.
   2. The current location of the executive is fetched.
      
      
      1. The permission to use the device's GPS unit is sought before the above step. If granted, the Location API of the browser is used.
      2. If GPS permission is not granted, then the executive's current city is used from his/her profile.
      3. If the current city is not set in the user's profile, then 'London' is assumed. However, the user is gently reminded that his/her location is not available and that the system is falling back to London.
         
         
3. The server returns the list of buildings nearby. In the first version, only the 3 nearest buildings will be returned. The returned information contains the following info.
   
   
   1. A short name for the building that is easy for the executive to look at a glance.
   2. The complete postal address of the building. This also has the contact details of key persons in the building. It is also possible to look this address up for navigation.
   3. The time required to commute to the building from the executive's current location.
      
      
      1. The Executive's device's GPS is required to calculate this.
      2. If GPS is not available right now, then this widget is instead shown as 'Please click to enable GPS'. Clicking on the widget will cause the web app to prompt the executive to enable GPS. The route is then calculated and the time to commute displayed.
      3. QUESTION: Who calculates the route and time taken? Is it the server or the web app? If it is the web app's responsibility, should the mode of transport be assumed as car or public?
      4. Clicking on the route estimated time will cause the web app to open the route on the phone's navigation app.
   4. The list of the floors / levels in the building and their names / numbers.
      
      
4. By default, one building and one of that building's floors is automatically chosen. The executive can choose another building and a floor.
5. Once a building is chosen, either automatically or manually, the lowermost floor / level of the building is automatically chosen.
6. Every time a floor is chosen, either automatically or manually, a new request to get the availability of different types of rooms on the floor is sent. Please note that this request must be accompanied by the executive's session token.
7. The server returns the availability information. Here is what is returned in a list.
   
   
   1. The name of the room type (e.g. conference hall, private pod, etc).
   2. The number of such rooms available.
      
      
8. In addition, the web app shows the sum of availability in an item called 'All'.

1. For each building and its each floor / level, a floor map is available. The executive can request for it by clicking on a link on the home page, after having chosen a building and a floor.
2. When the request is received, the server returns the floor map as an SVG file. The SVG is a canvas showing various shapes that form the contours of the floor. These are rooms, passageways and entry/exit points.
3. In addition to the floor SVG, a list is received. Each item in the list represents a rentable space on the floor. The following attributes are supplied.
   
   
   1. The pixel co-ordinates of the rentable space within the pixels of the entire floor SVG canvas.
   2. The category of room
   3. Whether the room is already taken or not
      
      
4. By default, after the floor map is loaded, all the rooms on that shown are represented by a dot. A green dot indicates an available room, while a grey dot indicates an occupied room.
5. The floor map also shows buttons, each representing a category of rentable space and one button representing all categories. Clicking on one of the buttons narrows down the number of dots shown on the floor map. Only the dots representing the category of the room chosen are displayed. All the other dots are removed from the map.

1. When the executive clicks on the settings icon, the web app makes a request for the executive's profile. The session token sent with the request identifies the executive whose profile is to be fetched.
2. The server returns the profile of the executive. The following fields are returned.
   1. The full name of the executive.
   2. The URL of the executive's photo.
   3. Phone number
   4. Email address, which is the same as the one registered. Except for this field, all other fields are modifiable.
   5. The current city of the executive. Note that this is actively set by the executive and NOT fetched through GPS.
   6. The preferred building of the executive.
   7. The preferred floor within the preferred building.
   8. The preferred department within the preferred building and floor.

• The profile modification request allows the executive to modify all the fields of the profile except for the email address and the profile picture.
• Email address modification is not possible since that is the user's login credential. In a future version, we may consider transferring an executive's profile from one email to another using authenticated mechanisms such as OTP / confirmation emails.
• The profile picture can be modified, but is a server request seperate from the one that modifies other profile fields.

1. When the executive modifies any field of his/her profile, a request is sent to the server.
2. The server makes changes to the database and acknowledges the changes in the response.
3. The following fields can be modified
   1. Name: Validation is similar to the validation used during registration.
   2. Phone number: A leading plus sign, followed by upto 16 numerals are allowed. QUESTION: Brackets?
   3. Location: The current city. This is selected from a list of cities supported by Freespace.
   4. Preferred building: The building at which the app should start.
   5. Preferred floor: The floor at which the app should start.
   6. Preferred department: The department on which the floor map should be centred to start with.

The room availability page and the floor map page also get live updates as soon as rentable spaces are occupied or vacated. Here is how it works.

1. After loading the page, the web app connects to the live update URL on the server via a web socket connection (ws:/ /url).
2. When the status of a room changes, i.e. if a room fills up or is vacated, the following packet is sent by the server over the websocket.
   
   
   1. The ID of the space. Each rentable space has its own ID in the system.
   2. The category of room (i.e. conference room, private pod, etc)
   3. Occupied or free (a boolean true is sent if occupied or false if free)
      
      
3. If the current page is the page of availabilities,
   
   
   1. If a space is occupied, then the count against that space goes down by 1.
   2. If a space is vacated, then the count against that space goes up by 1.
      
      
4. If the current page is the floor map,
   
   
   1. If a space is occupied, then the corresponding dot turns grey.
   2. If a space is vacated, then the corresponding dot turns green.
      
      

Here is a complete scope of what I need to deliver for the web app. This scope is technical in nature and will be accompanied by a formal, but shorter scope PDF document, which is also a proposal.

1. Web page: Splash screen
   1. A place to display product logo
   2. A place to display copyright information
   3. Message about the use of cookies on the web app
      
      
2. Web page: Registration
   1. Input fields: Text field for name and text field email address
   2. Validation for name and email address fields as described in the registration workflow.
   3. Submit button to invoke the API call for registration
   4. A hyperlink to allow a registered user to skip this page and go to login page.
   5. A panel to display registration error message
      
      
3. Web page: Successful registration
   1. Display message to indicate registration success and prompt the user to check mail.
      
      
4. Web page: Invalid confirmation token
   1. Display message to inform user that he/she may have used a tampered confirmation URL.
      
      
5. Web page: Generate password
   1. Input fields: A password field for 'Enter password' and a password field for 'Confirm password'
   2. A hidden input field to store the provisional session token for the user
   3. Submit button to invoke the API call for saving password to server
   4. A panel to display error messages from the server
      
      
6. Web page: Login
   1. Input fields: A text field for email address and a password field for the password
   2. Submit button: To invoke the API call to login
   3. A panel to display error messages from the server
   4. Use of cookies / local storage to store the user's session token
      
      
7. Web page: Home, i.e. availability of rentable spaces
   1. Use of cookies / local storage to retrieve the current user's session token
   2. API call to server to fetch the profile of the user
   3. A panel to display the current user's name
   4. Permission to use Location API
   5. Use of Location API to determine current location
   6. Display error message if neither GPS location nor the location on profile is available.
   7. API call to server to fetch the three nearest buildings and their floors.
   8. Horizontally stacked tab bar to display the three buildings
   9. Vertically stacked text panels to display the floor numbers, on the right for right-handed users and on the left for left-handed users.
   10. Vertically stacked text panels with tiny image thumbnails to display room categories and their numbers available.
   11. Click event on tab bar causes the following to happen
       1. Display the floors in that building.
       2. Invoke API call to fetch the room categories and availability of each
       3. Display the room availability
   12. Hyperlink to show floor map
   13. Listen for broadcasts from service worker (see point 9) and use the data received to update the page with the latest availability.
       
       
8. Web page: Floor map
   1. HTML canvas to display SVG
   2. API call to server to fetch the SVG floor plan of the floor.
   3. Render the floor plan SVG in the canvas.
   4. API call to server to fetch data about individual rooms on that floor.
   5. Vertically stacked text panels that display the names of each room category on the floor.
   6. Use of co-ordinates in room data to plot dots on the floor map SVG.
   7. Use of room's status to colour the dots either green or grey.
   8. Click event on the text panels in point e does the following
      1. If a room's category matches the category on the clicked panel, then display that room's dot.
      2. If a room's category does not match the category on the clicked panel, then hide that room's dot.
   9. Listen for broadcasts from service worker and use the data received to update the colour of the dots for the rooms whose live status is received.
      
      
9. Service worker for live room status updates
   1. Connect and stay connected with the server using web socket in order to receive live updates about status of rooms.
   2. When a room status is received, broadcast that message to the rest of the web app.
      
      
10. Web page: Profile
    1. Text panel to display the full name on profile
    2. Image panel to display profile picture
    3. Static text panel to display email address
    4. Text panels to display phone number
    5. Text panel to display current city and a dropdown to change it.
    6. Text panel to display preferred building within city and a dropdown to change it.
    7. Text panel to display preferred floor within building and a dropdown to change it.
    8. Text panel to display preferred department within floor and a dropdown to change it.
    9. A file upload control to allow the user to upload a new DP
    10. API call to the server to submit new profile details (other than email and DP)
    11. API call to the server to fetch list of cities.
    12. API call to the server to fetch list of buildings in a city.
    13. API call to the server to fetch list of floors in a building.
    14. API call to the server to fetch list of department on a floor.
    15. API call to the server to upload DP
        
        
11. Logout
    1. Delete local storage
    2. API call to server to delete session token