Requirements

Requirements and Gathering

Collecting the project requirements was fairly simple. Prof. Connor wanted a system to deploy Voiceflow bot designs to SMS. After a few discussion rounds, we settled on the following requirements:

Non-Functional Requirements

RequirementSeverity
Discover a method to export chatbot data out of Voiceflow, OR, research Voiceflow alternativesMust
Research the best platform for building SMS botsMust
The SMS bot should be no/little code environmentMust
Design a stable bot data formatCould
Design a stable API for SMS backendsCould
Produce implementations of these APIs for your chosen platformsCould
Document, test, and publish them as isolated npm packagesCould

Most importantly, this project is about research. The end result is clear, but it is unknown how to achieve it in a viable manner. We need to clarify how we receive and process Voiceflow data, as well as how can we create SMS chatbots using that data.

Proposing A Better System Architecture

As we developed the project, we saw that we largely depended on external APIs, backends, and file formats. All of these are prone to change. Also, if someone wants to adapt our project to a different chatbot data input (e.g. not Voiceflow) or a different SMS backend, they would have to change many aspects of the project. Also, the project was developed initially as a monolith application with little room for extensibility and few ways in which other developers can reuse some aspects of it in their work. Though this was fulfilling all of our client’s requirements, it seemed we could do a lot better here for the future aspects of the project.

We came up with the idea to split our project into 3 entities, standardise its APIs and data formats, provide concrete implementations of these standards, and publish them as self-contained software packages to be reused by other developers. Our client appreciated this progress and we added that to our optional requirements.

Functional Requirements

Once that is done, we can proceed with creating a functional system:

RequirementSeverity
The ability to convert any Voiceflow bot into an SMS chatbot with the same functionalityMust
Deploy the SMS chatbots under a specific phone number that can be chosen from a set of numbersMust
The ability to dynamically remap different chatbots to different numbersMust
User-facing application deployable on Windows / Mac environments or via a web APIMust
If is is via a web API, it should sit on a Linode platform and be deployable via DockerMust
The ability to remove deployed chatbotsShould
The ability to log errorsShould
If the solution is not standalone, enable a Voiceflow user to apply the solution via multiple browsers including Chrome and ExplorerShould
The ability to test a chatbot as if it was deployed on SMSCould
Have unit tests for core business logicCould
Have 95%+ code coverage for all business logicCould
Have full system E2E tests and test all probable system workflowsCould
Have UI unit tests for all UI pagesCould
Have full UI E2E tests (including business logic) and test all probable user pathwaysCould
Create 100% fail-proof input validation to guarantee that if the system accepts an input, it will be interpreted correctlyCould

The client proposed the should and must requirements. As the project developed, our team proposed to add all could level requirements. Our reasoning follows.

SMS Deployment

We proposed to add a requirement to test bots before SMS deployment. The idea is to simulate a chat interface for the user to text the bot as if it was already deployed. We thought that it was an important part of the system in order to guarantee safety before deployment. The client agreed.

Business Logic Testing

We wanted to guarantee that all of our business logic code works in all edge cases. This is why we placed a target of 100% code coverage for unit tests. In addition, because we wanted to separate our business logic in self-contained npm packages, making sure they work perfectly in isolation is key too. This is why, for every software package, we also aim to develop extensive full-system E2E tests that test every possible workflow of the library.

UI Testing

If the business logic modules are properly designed and isolated, then the UI code would simply call these functions and make it pretty. Therefore there isn’t much that “could go wrong” for a test to detect in a reasonable amount of code.

Nonetheless, we decided to go and write unit tests for all UI pages. This is an administrative UI, so however basic (in terms of logic) it is, we must guarantee that the pages/buttons/actions do what they should and that the views are updated accordingly with state.

In addition, we also decided to implement full UI E2E tests. These would simulate a real user clicking buttons and reading text from the screen and then navigating and achieving complex tasks. Tasks that require a sequence of steps, so would not be covered by mere unit tests. We think this is important to guarantee that after everything else, the whole system works as expected.

Input Validation

Our business logic represents two self-contained modules. These modules have inputs. The inputs are very complicated, representing multiple file format specifications. Nonetheless, we must guarantee that a module rejects an input that doesn’t fit this exact format.

For example, it could be that our external chatbot data source changes their format very slightly. We must be able to detect that and refuse to process it until a developer has confirmed that the software correctly interprets the new format.

Summary

In short, the client asked us to produce a user-facing application with Create, Read, Update, and Delete operations over SMS chatbots, and the respective research and implementation of some business logic.

In addition, we decided to greatly expand the requirement set with the aforementioned requirements. We could have stuck to the initial requirements and delivered them 2x faster. Therefore, we think this is worth noting as it shows the determination of our team to produce a good, impactful piece of software.