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. The server has mailed the executive a registration confirmation email with a confirmation URL. This URL contains a token that will verify the executive from a provisional status to confirmed status.
         
         
      3. 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. Whether the executive is left-handed or right-handed: The letters 'L' and 'R' are used to represent the dexterity.
   6. The current location of the executive. Note that this is actively set by the executive and NOT fetched through GPS.

• 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: QUESTION: What validation rules are applicable?
   4. Left-handed or right-handed: The letter 'L' is saved if the executive is left-handed, otherwise the letter 'R' is used. No other symbols can be used, be it letters, numbers or other characters.

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). - 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.
   
   - The ID of the space. Each rentable space has its own ID in the system. - The category of room (i.e. conference room, private pod, etc) - Occupied or free (a boolean true is sent if occupied or false if free)
   
   - If the current page is the page of availabilities,
   
   - If a space is occupied, then the count against that space goes down by 1. - If a space is vacated, then the count against that space goes up by 1.
   
   - If the current page is the floor map,
   
   - If a space is occupied, then the corresponding dot turns grey. - If a space is vacated, then the corresponding dot turns green.