# Project 2 Specifications

## Section 2: Overall Description
### 2.1: User Needs
The project we are working on in essence aims to facilitate the interaction of people with the table visualizer and editor through incorporating more sensory avenues to interaction. Rather than following the atypical format of having only sight and vision be the only mean of perceiving the app, the project incorporates a screen reader to read the tables and headers being visualized. Our users are able to visualize, edit, remove and update an SQL database imported into the app. They are able to navigate between the different databases and implement the same changes to all of them. The users are also able to see the caches on the terminal as they move between the databases and tables.

The biggest gap of the app at hand is the assumed ability of users to properly interact with the websites. Most table editors and visualizers rely heavily on the user’s ability to sight and read to use the features of the app. Through the development of a screen reader, we are hoping to defy and incorporate more accessible and intentional design into our services. We try to bridge this gap by offering an accessible experience to all of our users and not expanding the ways our app can be used.

Historically, web and computer services have been inaccessible for users that are visually impaired or unable to read. That limits the scope at which applications reach and also denies specific groups of humans from services that should be accessible to everyone. With the introduction of screen readers, a lot of users who rely heavily on those express frustration with the potential confusion caused by the narration. There needs to be a clear progression of material being read in order to better situate the user on where they are with the app and better understand its function. A lot of users also express frustration with the pace at which content is delivered and the lack of control they have over movement and navigation across the website. Similar to how visually abled people have the agency to control their interaction with apps using navigation tools, visually impaired users should also be able to do so with the screen reader.

With some research and brainstorming, there are many groups that can benefit from a screen reader. which means that its design and emphasis on better development will serve the greater purpose and number of people. The three groups we have identified are the following:
* Individuals who are visually Impaired (Both cases for visually impaired)
* Individuals who are unable to read
* Individuals who would like to learn spoken English

#### Individuals who are visually Impaired (Both cases for visually impaired):
* Building off the Microsoft accessibility framework the given PowerPoint borrows the three types of impairment (situational temporary, permanent), treating both impairments separately and developing separate tools for either deviates for an accessible future where disability does not distinguish people from one another. Services and products need to be inclusive of all and any inaccessibility is a flaw in the product.
* Clear description and navigation of the website in a coherent sense. This way it will best allow the visually impaired to better access the website and improve their interaction with its full functionality.
* Another option is allowing the user to identify words they would like to learn the spelling for. That is especially important when there are medical terms and or scientific terms in different languages that an individual would like to learn.
* Control of pace at which information is being read, and allowing for significant user control over movement between sections or allowing for long pauses. Not assume a standardized pace for all users as everyone has different paces at absorbing and learning information.
* A lot of users also express that artificial voices and synthesizers lead to a more lonely and unenjoyable experience.

#### Individuals who are unable to read
* Screen readers can also make web services and applications accessible for individuals who are unable to read. In this scenario, offering a form of visual indication to what is being read by the screen reader can allow the user to keep track of where they are on the application.
* Adding some form of manual navigation + reading options can allow the user to benefit from the visual design of the web apps while still being able to engage with the content in the format they most prefer.

#### Individuals who would like to learn spoken English
* Having some form of visual plus screen reading combination will also be helpful in this scenario, as users are will be able to learn the language through both reading and listening.
* An important feature for this group of users requires correct enunciation of words by the device.
* A lot of users also express that artificial voices and synthesizers lead to a more lonely and unenjoyable experience.

Two of the three groups of people would use the screen reader with the table visualizer almost constantly because their understanding and engagement with the product are dependent on the clear delivery of the content of the product. Others would benefit from an intentionally designed incorporation of both visual and speech factors.

Within these three groups, we could perceive English language learners as secondary users of the screen reader functionality. Other secondary users could be people who prefer to listen to read text rather than reading themselves as they prefer that means of utilization and interaction.

This application and the intended screen reader also potentially create and augment user needs that might have not been considered before. Incorporating and storing speech devices might cause an increase in data consumption. Users from low bandwidths areas might find these services less accessible. Therefore we need to find ways to combat that and ensure that the accessibility of our website and app does not differ considering the additional services.

Sources:
https://www.blindstreet.com/advantages-disadvantages-using-screen-reader-instead-braille/
https://www.microsoft.com/design/inclusive/

### 2.2: Assumptions and Dependencies
#### Technical Dependencies
- Our software depends on properly formatted `.html` files with vital information only within these following tags: TITLE, P, H1, H2, H3, A, IMG, FORM, TABLE, TR, THEAD, LABEL, INPUT
- Properly populated SQL databases with the appropriate information.
- Well-maintained API endpoints, a set of which can be used to query the appropriate data info at any given time.
- IntelliJ as an IDE and Java 17 jdk
- Maven as a package manager
- tsconfig.json as a Typescript compiler
- Github for file sharing and collaboration

#### Non-Technical Dependencies
- We are relying on the fact that the data that we are provided were gathered ethically with informed consent by the provider.
- We are assuming that the data are gathered in line with existing GDPR legalities
- We rely on the fact that our data in our database does not cause harm to society, including any acts of defamation, hate speech, and misinformation.

#### Normative Assumptions
- We are relying on the fact that users using the screenreader have the ability or resources to either recognize the keys on a keyboard then manually press them and/or have a method to click on buttons at the top of the screen with labels.
- We make normative assumptions about users’ level of access to technology (i.e. internet) and their English proficiency in listening.
- We make normative assumptions that users have access to Firefox or Chrome as a web browser as other browsers may not be supported by typescript.
- We make normative assumptions that our users have visual abilities for the table visualizer and highlighting portion of screen reader.

#### Financial Dependencies
- Continued free access to JetBrain IDEs through Brown
- Funds for replacing personal computers, if needed
- Continued availability of adequately powerful free tiers in services like GCP and Firebase

## Section 3: System Features and Requirements
### 3.1: Risks
#### Stakeholder Risks
- **Missing Information:** We may have the risk of missing on informing vital information to the user since we only support certain Elements from the DOM for screen reader. If the author of a html file decided to include crucial information that affects the user experience on the site in an unsupported HTML element, we would be denying them the right to information.
- **Disproportionate benefits:** Currently, we are prioritizing individuals who are visually impaired, individuals who are unable to read, and individuals who would like to learn spoken English. There will definitely be demographics who need a screenreader who will not benefit nearly as much as our prioritized groups which is unfortunately a shortcoming of our design.
- **Publicly accessible data:** All data in our html files and sqlite3 files are completely accessible to the user. We would have to ensure that the entire file does not contain any private information that we would not want users to see. In addition, we currently do not use API keys to restrict certain users from certain data. Thus, the previous caution we could have to take is even more crucial.
- **Non-consensual data harvesting:** We currently do not have a method to check the source and citation of the sqlite3 file to know whether the data we are presenting in tables are ethically sourced. A possibility of this would be presenting data that was acquired through Non-consenual data harvesting which may include stealing potential income to writers, artists, and other creators.

#### External Risks
- **Community wellbeing / harmful information:** Like stated previously, we currently do not have a method to check the source and citation of the sqlite3 file, much less, the content. Thus, if our program is used by other engineers, we do not have the current implementation to restrict publication of certain harmful content such as acts of defamation, hate speech, and misinformation. This could cause mental harm to affected demographics and help spread sexism, racism, classism, and other harmful prejudice.
- The span of our project extends to the astrological signs at Brown University, an institution that resides on Native American land and was built using slave labor. In indirectly supporting this institution, we also must recognize the harm that has been done and continues to be done by the institution.

### 3.2: Data Requirements
All data were either given to us by the course or composed by us, which currently ensures that all contents are appropriate and safe.

| Datum name | Storage/Access | Purpose |
|--------------------------|-----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| HTML Element with "P" Tag | Stored as a field for ElementHandler (additionally, it is public data accessible to anyone through inspect) | needed to highlight and read off text to user for screen reader |
| HTML Element with "TITLE" Tag | Stored as a field for ElementHandler (additionally, it is public data accessible to anyone through inspect) | needed to read off title of document to user for screen reader |
| HTML Element with "H1" Tag | Stored as a field for ElementHandler (additionally, it is public data accessible to anyone through inspect) | needed to highlight and read off text to user for screen reader |
| HTML Element with "H2" Tag | Stored as a field for ElementHandler (additionally, it is public data accessible to anyone through inspect) | needed to highlight and read off text to user for screen reader |
| HTML Element with "H3" Tag | Stored as a field for ElementHandler (additionally, it is public data accessible to anyone through inspect) | needed to highlight and read off text to user for screen reader |
| HTML Element with "A" Tag | Stored as a field for ElementHandler (additionally, it is public data accessible to anyone through inspect) | needed to highlight, read off text to user for screen reader, and retrieve link if user's interaction demands it |
| HTML Element with "IMG" Tag | Stored as a field for ElementHandler (additionally, it is public data accessible to anyone through inspect) | needed to read off information of image to user for screen reader |
| HTML Element with "FORM" Tag | Stored as a field for ElementHandler (additionally, it is public data accessible to anyone through inspect) | needed to help indicate to screen reader users that a form is beginning |
| HTML Element with "TABLE" Tag | Stored as a field for ElementHandler (additionally, it is public data accessible to anyone through inspect) | needed to help describe table in site and help indicate to screen reader users that a table is beginning |
| HTML Element with "TR" Tag | Stored as a field for ElementHandler (additionally, it is public data accessible to anyone through inspect) | needed to indicate new row is beginning for table |
| HTML Element with "THEAD" Tag | Stored as a field for ElementHandler (additionally, it is public data accessible to anyone through inspect) | needed to indicate that row/cell is a header for column |
| HTML Element with "LABEL" Tag | Stored as a field for ElementHandler (additionally, it is public data accessible to anyone through inspect) | needed to highlight and read off text to user for screen reader |
| HTML Element with "INPUT" Tag | Stored as a field for ElementHandler (additionally, it is public data accessible to anyone through inspect) | needed to highlight and read off type for input
| HTML Elements with other Tag | stored as part of the collections of elements we parse through | the elements are never stored, only parsed through |
| sqlite3 files | the information is never stored, only before the json is sent to the frontend | needed to present table to local host site in the frontend |
#### Backend Portion
For the backend, will not need to collect personal data from the users, we will have to however store the information from the SQL files and from any edits that the user puts in. However, that does not require any personal information to be stored in the backend.
### 3.3: System Features

#### How to build/run the program

**Screen Reader**:
Open the html file in either Chrome or Firefox to access the html site with the screen reader functionality.

Note: If the .js file has not been compiled, then users should navigate to the frontend/screenreader folder in the terminal and then input `tsc -w` to compile the javascript file from the typescript file.

Additionally, all relevent files are in frontend/screenreader including screenreader.ts/.js

**Table Visualizer**:

In order to run the backend, navigate to the `backend` package and input to the terminal `mvn package` and then `./run --gui`. The REPL will then execute its run method and the user can input their commands. In order to connect a database, use the command `load_table <path/to/database.sqlite3>` and ensure that it has been loaded with a successful response.

In order to run the frontend, start the server by running `http-server` in the `frontend/table` directory and then navigate to `localhot:8080/table.html` in a Chrome or Firefox browser, where you can see the structure of the webpage. Assuming that you have successfully loaded a database via the `load_table` command, the database can be loaded and visualized here.

We will organize our classes into packages based on what they are used for. Class- and package-specific documentation can also be found by running `mvn site` and opening the generated `allpackages-index.html` file in the `target/site/apidocs` directory using your web browser.

- `main` package: Contains `Main` and `FrontendSuite` classes. The `FrontendSuite` contains all of the `Evaluable` command classes necessary for the project. Also contains the packages listed below.
- `REPL` package: Parses through terminal inputs and calls the execution of commands. `Evaluable` commands can be executed by the `REPL` via the `Evaluator` class. `Evaluable` commands are stored in a specific `CommandSuite`, which allows data to be shared among multiple commands.
- `CSVParser` package: Stores classes related to the functionality of a generic CSV parser. Also supports generic string parsing by any delimiter, which is used by the REPL.
- `DatabaseProxy` package: Contains a `Proxy` class, which simply allows connection to a `sqlite3` database by a filepath and can execute SQL queries on that database.
- `TableResponses` package: Contains classes that implement the `ServerResponse` interface, all of which are containers for data that can be sent to the frontend in the form of a Json. These container classes are meant to be restricitve wrappers for data structures, limiting the operations that can be done.
- `TableRequests` package: Contains classes that extend the `RouteHandler` abstract class, which serve as handlers for the different supported API endpoints. A `DatabasePathNotFound` exception will be thrown in this class if a database has not been loaded via the `Evaluavle` REPL command for loading a database, which is stored here.

#### Frontend features:
- **Screen Reader:** allows for user have auditory aid of information on the screen through a screen reader speech voice and visual aid of highlighting information the screen reader audio is current reading.
- **Table Visualizer:** allows for a user to visualize a `sqlite3` database and all of the table contained in the database file.

#### Backend features:
- **Frontend communication:** able to connnect to a database via the `load_table` command and query information from that database in order to gather information needed by the frontent. Maintains the endpoints "load" and "table" that can send information to the frontend in order to visualize the database.
- **Database alteration:**:

### 3.4: Functional Requirements
#### Screen Reader
Located in the `frontend/screenreader` folder, screen reader is able to read off the contents of an html page including the handling of tables, images, and interaction with buttons and input boxes with adjustment features for speed, skipping, and pausing.

Format: `button name [keypress]`
- `start [Space]`: starts the screen reader to begin reading the html site.
- `Pause/Resume [P]`: pauses the screen reader if screen reader is reading. Resumes the screen reader if screen reader is paused.
- `Speed Up [Right Arrow]`: Speeds up the speech of the screen reader by a factor of 1.1
- `Slow Down [Left Arrow]`: Slows down the speech of the screen reader by a factor of 0.9

Special Cases:
- `[Enter]`: when a link is present and the user is prompted, the user can press enter to go to the site the link is linked to.
- `[c]`: when an element with an `INPUT` tag appears, the screen reader will stop and inform the user to press `[c]` to continue or type in information then press `[c]` to continue. For submit buttons, `[Enter]` is the same case

#### Table Visualizer
Located in the `frontend/table` directory, the user-facing fucntionality of the table visualizer is contained in the `table.html` and `table.ts` files. After successfully loading a database into the backend, a user can use the "Load data" button that appears on the HTML page to load the table names from the database as well as the first page. By using the `<select>` dropdown menu, the user can change which table within the database is being viewed. If a new database is loaded into the backend, the user must press the "Load data" button again before querying tables from that new database.

### 3.5: Testing Plan
Testing will be broken into two parts: one that shows that the features work as intended and the other that shows errors occur appropriately with faulty inputs. Mentioned edge cases and tasks are tested through extensive System and Unit Testing.

#### Table Visualizer

For the table visualizer, an additional `sqlite3` file was made (named `test.sqlite3`) and tests also utlize other example files including student data, horoscopes, and zoo data. Unit testing was completed where possible for all Java classes made in the backend.

System testing was completed by loading all of these example `sqlite3` files and visualizing all the tables in these files in the frontend, ensuring that the data represented (table names, table data) was being dispayed properly.

#### Screenreader

For screen reader, additional html test files were made for testing.
- **no_form_info_test.html:** This file was for testing whether users for screen reader could still recognize and be informed about a form without any of the elements surrounding the form indicating that a form is present (like in screen_test_3.html).
- **no_image_description_test.html:** This file was for testing whether users could still gain any insight on embedded images without an alt tag. The image file name was spoken instead along with informing the user that no description of the image was included by the html file.
- **yellow_body_background_test.html:** This file was for testing whether the screen reader could change their highlight color in the case that the document body background color was the same as the yellow highlight.
- **yellow_row_background_test.html:** This was similar to yellow_body_background_test.html, but testing if the row element of a table's background color was the same as the highlight color as different parts of the website may be in different colors.

### 3.6: External Interface Requirements
Unlike the previous sprints, this project utilizes user-facing features beyond interacting with the REPL.

Our external interface will be the opened HTML files on either Chrome or Firefox. Related Commands for screen reader will be accessible through the opened HTML file and user's keyboard.

Users will interact with our table visualizer via the `table.html` file/website. As we are implementing a screen reader for reading HTML files, we are taking a particular focus on making our app accessible to those with visual or cognitive impairments that make reading challenging. Due to this focus, however, other limitations are less accounted for. For example, the database must be loaded via a REPL command in the backend before loading data, and little differentiates a failure to load the database from a technical failure or loading an empty database; as such, individuals with less experience and/or technical knowledge might struggle to use our app.

We will not be integrating any other external softwares yet.

### 3.7 Non-functional Requirements
- **Performance:** We aim for most backend operations to be achievable on the timescale of several milliseconds. Communication between the front and backend must wait for responses, so the operations done within the backend must be fast in order to minimize the total wait time for each operation, such as loading a table. For the front end, especially screen reader, users will have control on the speed of the voice synthesizer. However, the default speed of the voice should be reasonable to the majority of our users. All in all, our only major performance concern is that users do not notice any delays between the inputting of their commands and their execution.
- **Security:** As we start integrating features for editing data from the database, we must ensure that only users with the correct permissions can edit the data in their requests.
- **Privacy:** Once again, as some data used on the potential website may be private, we must ensure that only users with the right access is granted access to the data from the database.
- **UI:** While our goal for the UI is not to be “flashy” or otherwise impressive looking, some effort to increase visual appeal should be made; this includes minor color and margins/padding with CSS. Our other UI capabilities are dependent on the HTML website used for the screen reader. Additionally, another interface users will use will be on the REPL, solely to load the requested database into the backend. The focus of our app is accessibility, especially with accessibility that is related to visual or cognitive impairments that make reading challenging. Our screen reader component aims to make any arbitrary HTML UI accessible in this way.