Architectural Decision Records - cse110-sp24-group23/dev-journal GitHub Wiki
Contents
- Using GitHub Projects
- Using localStorage to make and maintain the database
- Style Guide
- Using SimpleMDE for Markdown Functionality
- Using Cloudflare for Hosting Page
Our ADR files can be found in docs/adr.
Using GitHub Projects
Context and Problem Statement
How do we keep track of our agile process?
Which tool would be ideal to support real-time collaboration?
Considered Options
- Manually
- Using a Scrum tool
- Github Projects
Decision Outcome
Chosen option: "GitHub Projects" because it provides structure and a framework to keep track of our agile workflow and reduce complexity while collaborating. We could be able to have all our progress consolidated inside the repository, which would help us maintain a centralized record from planning till delivering the finished product.
Using localStorage to make and maintain the database
Context and Problem Statement
How should we store the data that the user saves? How much data is expected to be saved by users?
Considered Formats to Store Data
- JSON
- SQLite
- localStorage
Decision Outcome
Chosen option: localStorage
Using localStorage allows us to use built in features to accomplish our functionality without adding complexity. It gets rid of the need to include dependencies. It will also save us time because we will not have to worry about the learning curve that comes with using a tool that most of the team is unfamiliar with.
Style Guide
Images used in the style guide are available to view on the Style Guide ADR file
Context
Branding, colors, typography, and logos are all essential for conveying an identity to users. As a work documentation app, Noted should be catered towards professionals that want to keep a daily log of their accomplishments and more. Functionality and aesthetics should be simple and effective, leaving little to no room for user confusion. Branding should be both reflective of the app itself as well as the team.
Goat Logo & Branding
A goat was chosen for our logo in order to reflect our team branding. We are team 23 of CSE 110, and decided to name our group "LeGroup" after Lebron James because he wears the number 23 on his jersey. Rather than choosing to use an image of Lebron as our logo, we decided to use a goat, as many refer to Lebron James as the GOAT, or Greatest of All Time. The colors of the goat were stylized according to our brand colors, and we wanted the goat to appear friendly and simple, much like our web app.
Colors
Dark blue, black, and white were chosen to be the colors due to its professional tone and clean, minimalistic feel. In the case of our website, we did not want the aesthetics of the site to distract from its utility and usability, but rather to complemement it. By keeping the branding colors simpler, we can allow for more diversity of color within the objects of the site itself, such as notes, or calendar days. Note colors were chosen to be pastel colors to ensure readability of the text overlay, as well as distinguishability between notes.
Typography
The sans-serif font "Lato" was chosen to represent both the fonts for the headers and body text of the web application. First and foremost, sans-serif fonts provide more readability on screens due to the clean lines and lack of decorative elements. It also because of this that sans-serif fonts tend to scale better with various screen sizes and resolutions. Additionally, the clean, minimalist design of the sans-serif font "Lato" conveys a modern and professional look, which complements our brand identity. As stated earlier, the fact that our font can be used as both headers and body text is a strength of the versatility of sans-serif fonts. Lastly, importing custom fonts could introduce dependency on a third party or can introduce further load times for the user, which would be unneccessary.
Logos & Icons
Logos and icons were compressed into svg file formats to optimize image file sizes, which helps our performance. As stated with the typography, minimalism, readability, and accessibility were the main rules that we wanted to follow when making our logos. Universally recognized symbols should be used to represent its associated object. Thick lines should also be used to ensure readability and reduce complexity of the icon. As more icons/logos are produced, they should be able to say "Yes" to the following questions:
- Can its associated tool/object be easily understood from the icon/logo?
- Does the icon/logo contain as little lines and points as possible?
- Does the icon/logo fit with the existing icons and logos? (i.e. There should be no sharp edges)
- Is the icon/logo compressed into a file format that is most appropriate?
- Does the icon/logo follow the color palette of the style guide?
More Decisions and Reasonings
A high-contrast mode and a dark mode were considered to be add-ons for Noted.
A high-contrast mode would improve accessibility, improving readability for users with visual impairments, such as low vision or color blindness. This mode would make it easier to distinguish between text and background.
A dark mode would help reduce the amount of blue light emitted by screens, which would minimize eye strain in low-light environments, making extended usage of Noted more comfortable. Users may also simply opt for dark mode due to its moder, sleek aesthetic appeal and comfort.
Due to the iron triangle constraint of time, our group opted not to create these two modes, as implementing different styles across our whole application would take considerable time and lower the quality of our main, dominant style. These two options will be reconsidered at a later date when essential features have been created and tested.
Using SimpleMDE for Markdown Functionality
Context and Problem Statement
We want a way to implement markdown editing in our dev journal to allow developers to style their logs and notes. We want to find a simple embed that allows us to save text in a markdown file.
Considered Options
- PandaO Editor
- Customizable but would add complexity, and writeup was in a different language
- Only split screen view for editor (editing side and preview side)
- Toast UI Editor
- Feature bloat: too much added functionality
- Mark Text
- Documentation was not good
- Output into PDF or HTML files, but we want to save in Markdown files
- SimpleMDE
- Easily customizable
- Simplest option out of the researched editors
Decision Outcome
Chosen option: SimpleMDE
We will use SimpleMDE for markdown editing in the daily logs and notes. SimpleMDE was customizable and streamlined, and many people recommended it over other editors. We want to include the autosaving feature and customize their toolbar to provide the most important styling options. We could also style this embed to align with our style guide. There is the potential for an XSS attack where a user could inject JavaScript through a link to a script tag, but because this is a local application with only the user’s data, there is no vulnerable data that an XSS attack could exploit. We decided this wasn’t a large enough issue to discourage use of Markdown text editing.
Using Cloudflare for Hosting Page
Context and Problem Statement
Github Pages only allows the hosting of a single site (branch) at a time.
We wish to end-to-end test on each different branch, because testing on main would be moot point.
We also want to host documentation, but again run into the same issue with GitHub
Considered Options:
- Cloning branches into seperate repos and hosting those in the Github Action
- Cloudflare Pages
- Having stunted E2E Tests
Decision Outcome
Option: Use Cloudflare
It's fairly obvious - Cloudflare lets us have an absurd number of "preview" pages, thus we can have one for each branch (or even push). This let's us do end to end testing fairly effectively, while also not making a heinous github action that copies things all over the place. Cloudflare has the wrangler github action which makes deployment simple, and we can use secrets to deploy, meaning no hard coding. Lastly, with the "infrastructure" in place, we can also host our documentation site with relative ease.