Requirements
Previously named Laniakea
- Overview
- Who is it for?
- Why build it?
- What is it?
- Project Goals
- Stakeholder Requirements
- Success Criteria
- Minimum Viable Product
- User Stories
- Components
- Mockups
- Tech Stack
“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 will be built primarily as a browser extension for Chromium based browsers.
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
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. Automatic tag suggestions for repos based on user activity is under consideration for a future release. Laniakea will try to encourage sanitation of existing stars while promoting immediate tagging of new stars with notifications.
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
- 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
- No drag and drop functionality for tags
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
User stories can be found on their own wiki page here
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 |
| Libraries | ReactJS, Jest, react-testing-library, styled-components |
| Remote APIs | GitHub API |
| Source control | GitHub |
| Project Management | ZenHub boards on Github, GitHub Issues |
| 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