Requirements
“All your stars in one place”
Laniakea is an application for categorization and re-discovery of starred GitHub repositories. It aims to improve on GitHubs existing starred repository system by allowing users to tag repos with labels that make sense to them and the use these labels to filter their stars down to that one perfect repo when they need it.
Laniakea is for active GitHub users with a large number of starred repositories and are frustrated by the lack of organizational tools provided in the standard GitHub interface. Laniakea can be used by developers with a Basic or Pro account.
- With 250 starred repos and 45 private repos, I have an immediate need for Laniakea’s core functionality
- I believe it will be useful to other developers
- It’s a strong portfolio project to show future clients/employers showcasing a variety of design and development skills
- It’s a good project to dig deeper into UX and Design
- Improve my project management workflow
Detailed Description Laniakea is named after our galactic supercluster and is Hawaiian for ‘Immeasurable Heaven’. It seems like an apt name for something resulting from too many stars.
GitHub gives users limited functionality for sorting their starred repos. You can list them all in one big list, apply a handful of filters such as detected language, date starred or by the name of the repo. This is ok if you only have a handful of starred repos but if there’s one thing the internet has burned into our habits it’s clicking a ‘Like’ button whenever possible. In the case of GitHub this leads to hundreds of starred repositories and limited ability to sort them making the star system less useful overall.
Laniakea seeks to offer tools for categorizing repositories so users can find them later using the same tags. For instance a user might add ‘Web Development’, ‘JavaScript’ and ‘FrontEnd’ tags to a ReactJS repo. They might add ‘Game Dev’, ‘C++’ and ‘Shaders’ tags to their search criteria to quickly find shaders for their next game. Users can add whatever tags they want to a project. The more tags, the more opportunity to granularly categorize and find them again later. Users can take those same tags and stack them in a search box to filter out projects in real time.
This is a small but impactful addition to a developers toolkit and there is room to expand the application further as a primary tool for sorting repositories and improving re-discoverability. The downside... Users will have to manually add these tags. Laniakea will automatically add the detected language as a tag but the rest is up to the user. This is the price of the customizability offered by Laniakea. We will however seek to ease this burden by notifying users of starred repos without any tags. Also planned is automatic suggestions of tags for repos based on user activity. Laniakea will try to encourage sanitation of existing stars while promoting immediate tagging of new stars.
Laniakea should enhance the existing GitHub stars feature by adding more control and ease of access. Laniakea should feature:
- Strong advantage over existing solutions
- Clean and modern visual design
- Intuitive interaction
- Trustworthy installation and authentication
- Clear and useful onboarding
- Stable and performant feature set
- Developer goals
- User focused and well documented design process
- Well planned and disciplined project management
- Clean, readable, testable and well documented code
- Open source project to display to clients and employers
- Gain experience with new tech ( React Hooks, react-testing-library )
The developer is the sole stakeholder. There will be no investment in the app, other than the developers time time. Laniakea will not be monetized and there is no expectation of an income. The stakeholder requires
- Demonstration of design and planning ( requirements, user stories, kanban, milestones )
- Portfolio project exhibiting use of a remote api
- Portfolio project exhibiting a solid grasp of unit testing
To be deemed successful, the app should:
- Add utility to the existing GitHub stars system
- Stable, modern and future proof tech stack
- Be released to at least one storefront (Firefox, Chrome, Windows Store, etc.)
- Evidence an expertise of the tech stack used to build it
- Open source code to the public
Minimum Viable Product will consist of core functionality using browser local storage.
- Search results will be displayed as a list with no controls over layout
- There will be no authentication with GitHub
- There will be no notifications
- App will be compatible with Firefox only
- App will have limited responsiveness with a focus on wider screen widths
Presenting a trustworthy stance is important for an app which requests access to a developers GitHub account. To facilitate building trust, the following steps will be considered.
- Allow limited app usage without authenticating
- Use a trusted method for authentication
- Be very clear about which account permissions are required and why
- Allow multiple levels of authentication with different permissions sets. No need for private repo access if user only wants to save settings to Gist
- Allow user to opt out of any other information collected
- Make collected information anonymous
- Carefully vet third party libraries used in development
Unauthorized User A user who has not authorized the app with GitHub and thus has limited functionality.
Authorized User A user who has authorized the app with their GitHub account and has unrestricted functionality available.
User task flows are detailed in the appendix
The following user stories have been considered and are detailed in the appendix
- As a user I want a stable and bug free app experience
- As a user, I want to easily access my starred repositories
- As a new user, I want to start using the app without authenticating, so I can decide if the app is useful to me
- As a GitHub user, I want to securely manage access to my account
- As a user, I want to confirm that I am authenticated for the correct GitHub account
- As a user, I want to quickly jump to my GitHub profile
- As a user, I want to browse starred repos
- As a user, I want to add custom tags to repos
- As a user, I want to list and reuse previously created tags
- As a user, I want to edit existing tags
- As a user, I want some sensible default tags when I first start using the app
- As a user, I want to filter repos by search term
- As a user, I want to filter my repos by tag
- As a user, I want flexible result filtering, so my search terms do not need to be perfect
- As a user, I want feedback on my repo tag maintenance so I can better configure tags to work with my repos
- As a user, I want to speed up the time it takes to tag my repos
- As a user, I want to backup/restore my app settings
- As a user, I want to know about updates to the app
- As a user, I want to give feedback to developers
App is primary container view. App is split into 3 primary views; AppBar, SearchPanel and Result Panel.
AppBar is a toolbar containing top level app components. It wraps the Settings button, Notifications button and the users GitHub avatar.
SearchPanel wraps all search and tag management functionality. Creating and editing tags is handled through the ### TagPalette sub-components. Searching is handled through the SearchBox sub-component.
ResultPanel wraps sub-components for displaying search results. Primary sub-components are ResultToolbar and ResultList.
SettingsMenu contains all top level application settings. All administrative task begin here such as handling user authentication and data sync management.
SearchBox handles user input of search terms and tags. Contains a TextInput element and a TagList component.
TagPalette is responsible for creating and managing tags. It consists of a TextInput field to search for tags, a TagList to contain tags and a few buttons to create, edit and delete tags.
TagList contains a list of tags. It is reused in a number of places throughout the app.
Tag is small, labeled element used to categorize repos and filter search results.
ResultToolbar wraps components for displaying result count and switching layout in the ResultList
ResultList is the primary component for displaying search results. Largest component on screen.
UserAuthModal is where the user specifies a GitHub account to work with. This is also the entry point for authenticating with GitHub.
GistSetupModal This window provides a dialog for users to setup Gists for backup and syncing data.
Laniakea should be design to evoke familiarity and trust among users familiar with GitHub. The default colour scheme will mirror that of GitHub and general design language will be carried over where possible. Laniakea should be visually appealing, giving a sense of competence at a single glance. Layout should provide sensible separation of primary functions and promote an intuitive understanding of application workflow.
Desktop
Mobile
UserAuthModal
GistSetupModal
Settings Menu
Menu
| Platforms | Chromium browsers (Chrome, Firefox) |
| Distribution | Firefox AddOns, Chrome Web Store |
| Languages | JavaScript, HTML, CSS |
| Libraries | ReactJS, Jest, react-testing-library, styled-components |
| Remote APIs | GitHub API |
| Source control | GitHub |
| Project Management | GitHub Projects |
| Documentation | GitHub Wiki |
| Community Engagement | GitHub Issues, Store user review pages |
Users do not need to authenticate with GitHub to use basic app features. By adding a username they can immediately view and tag starred repositories, saving app data to local storage. This is possible because GitHub stars on public repos are not private. To use advanced features such as syncing settings to Gist, users will need to authenticate the app with github, giving it appropriate permissions.
Laniakea uses OAuth2 for authentication with GitHub. OAuth2 allows the app to request specific, minimal permission from the user in a secure manner.
Laniakea utilizes the following permissions:
Gist - optional Gist access allows users to save Laniakea settings to a gist, enabling users to backup and sync their Laniakea settings
Repo - optional Full repo access allows users to include their own private repos in search results
As a user I want a stable and bug free app
- App is built using a well-established and stable framework
- App uses unit and integration tests to validate features
- App user browser cross-compatible styling and features
As a user, I want to easily access my starred repositories
- App is deployed as a browser extension for both Firefox and Chrome
- App loads in a new window on button click and immediately loads repo data
- App can be deployed as a Progressive Web App or Electron app for native experience cross platform
As a new user, I want to start using the app without authenticating, so I can decide if the app is useful to me
- App only requires login to use certain features
As a GitHub user, I want to securely manage access to my account
- Accounts are authenticated with a GitHub Personal Access Token with minimal permissions
As a user I want to confirm that I am authenticated for the correct GitHub account
- App displays user profile image
- App displays username in the settings panel
As a user, I want to quickly jump to my GitHub profile
- Clicking the user profile image will open their GitHub profile in a new page
As a user, I want to browse starred repos
- The app will fetch a list of the users starred repos
As a user, I want to add custom tags to repos
- The user can create tags with any name and add them to repos
- The user can add as many tags as they want to a repo
As a user, I want to list and reuse previously created tags
- User created tags are added to a list for reuse
- Users can filter the tag list by search term
As a user, I want to edit existing tags
- Users can change the name of an existing tag.
- Changing a tags name will update the tag on all applicable repos
- Users can set tag colors
As a user, I want some sensible default tags when I first start using the app
- App will use GitHub's existing detected languages as default tags, giving the user a good base for filtering their repos
As a user, I want to filter repos by search term
- Users can use any search term to filter repos
- Search terms can be comma separated
- Search terms with spaces will be first matched as a sentence, then as individual words
- If a typed search term matches a tag, the tag will be substituted for the search term
As a user, I want to filter my repos by tag
- Users can add tags to the search box to refine result
As a user, I want flexible result filtering, so my search terms do not need to be perfect
- The app can filter and arrange results by exact match with all entered search terms matched some search terms
As a user I want feedback on my repo tag maintenance so I can better configure tags to work with my repos
- The app allows users to filter repos with few tags so they can spend a moment categorizing them
- The app allows users to filter new repos that they have never tagged before
As a user, I want to speed up the time it takes to tag my repos
- The app can search a database for tags other users applied to a given repo
- Users can choose to anonymously share which tags they added to which repos
As a user, I want to backup/restore my app settings
- Sync settings with Gist
- User can specify a Gist id to sync with or create a new Gist
As a user, I want to know about updates to the app
- The app contains a change log outlining changes and version updates
- The change log will have a notification icon when updated
- The app will have a link to its repository so users can track commits
As a user, I want to give feedback to developers
- The app will have a feedback form where users can report bugs and leave feedback for the developer
- The app will have a link to the store page so users can up-vote
- Users can leave feedback in GitHub issues
Setup account from UserSetup window (unauthorized user)
- User enters their GitHub username when requested in UserSetup window
- User presses enter and begins to explore the apps functionality
Setup account from UserSetup window (authorized user)
- User presses Login With GitHub
- User proceeds to login to GitHub at the provided prompt
- User returns to the app and begins to explore the apps functionality
Change account setup
- User clicks on Settings button
- User selects Account Setup
- Goto: Setup account from UserSetup window
Search for a repo by name
- User clicks SearchBox in the SearchPanel to focus it
- User begins typing search term
- User views search results in the ResultsPanel
Search for a repo by tag
- User moves mouse to TagPalette
- User drags a tag from the TagPalette into the SearchBox.
- User views search results in the ResultsPanel
Remove a tag or search term from search box
- User moves mouse to SearchBox
- User clicks a Tag to remove it
Create a new tag
- User clicks the new tag Button in TagPalette
- User enters a name for the new tag
Delete a tag
- User clicks the delete Button in TagPalette to activate delete mode
- User clicks a tag to delete it
- User confirms deletion in confirmation window
Add a tag to a repo
- Path A
- User drags a tag from TagPalette onto a repo
- Path B
- User clicks + Button on a repo to highlight tag palette
- User begins typing tag name to filter tag list
- User clicks tag to add it to the repo
Remove a tag from a repo
- User mouses over a tag on a repo to highlight it’s close button
- User clicks a tag to remove it from a repo
Un-star a repo
- User clicks star on repo
- User confirms action in confirmation window
Change result layout
- Use clicks LayoutToggle to switch layout
Filter results by star count
- User clicks filters menu in ResultsToolbar
- User selects star count as desired filter method
Create new Gist for settings sync
- User clicks settings menu button
- User clicks Manage Settings Sync to display Gist setup screen
- User clicks Create New Gist
- User enters desired Gist ID when prompted
- User confirms action
Set Gist ID for settings sync
- User clicks settings menu button
- User clicks Manage Settings Sync to display Gist setup screen
- User clicks Use Existing Gist
- User enters desired Gist ID when prompted
- User confirms action
Include private repos in results
- User clicks settings menu button
- User clicks Include Private Repos In Results menu item to activate
Share usage information
- User clicks settings menu button
- User clicks Share Usage Information menu item to activate
View information about the app and author
- User clicks settings menu button
- User clicks Include About menu item to open about window
Leave bug report, feature request or feedback
- User clicks settings menu button
- User clicks Include Feedback menu item to open feedback window
- User selects between
- Bug report
- User is forwarded to GitHub issues
- Feature request
- User is forwarded to GitHub issues
- Leave feedback on store page
- User is forwarded to store page