Projects Tech Spec

[timmyichen]

Summary

This is the Discord feature we've always wanted but could never get prioritized. A project board featuring all the projects of 100devs.

Scope

In scope:

• Listing projects
• Filtering project by tech stack (will be the same as skills in Filtering Tech Spec #111)
• Pulling project info/activity from GitHub
• Creating a project / claiming ownership of a repo
• Updating a project
• Deleting a project

Out of scope:

• Tagging projects
• Searching for projects
• Project participation on a user-by-user basis

Data Model

New table: projects

Column	Type	Notes
id	int	primary key
name	string	name of the project, max len 255
repo_id	int	github's id for the repo
repo_full_name	string	full name for the repo (e.g. namespace/repo-name), used to create URL
discussion_link	string	link to the discord thread/post for discussion, max len 255
owner_id	int	foreign key to users.id
description	text	description of the project, max len 1000
status	string	actually an enum*, see values below

Plus timestamps

status enum values:

• building_mvp
• launched
• maintenance_mode

New table: github_access_tokens

Column	Type	Notes
id	int	primary key
user_id	int	foreign key to users.id
access_token	string	encrypted github access token
expires_at	timestamp	timestamp representing when the token expires

Plus timestamps

User Stories

• Users will be able to list all the 100devs community projects that have been added through PairUp
• Users will be able to create a project based on a public github repo they own
• Users will be able to edit the project they create, setting the name/description/status, and linking to the Discord discussion link
• Users will be able to filter projects by tech stack
• Users will be able to delete a project that they own

Implementation Details

A new page is created that facilitates all interactions involving projects:

• Lists all projects
• Has a call to action that allows creation of a project
  • Upon clicking, oauths with github to get an auth token
    • Auth tokens are configured to last 30 minutes (it is communicated to the user how long they have until they have to re-auth with github)
    • Auth tokens are persisted to a DB with an expiration time (enforced both by DB as well as by GitHub App config)
    • Auth tokens are encrypted before storing to DB
  • Using the auth token, we'll fetch their repos via this endpoint
    • visibility=public
    • affiliation=owner,organization_member
  • Upon selecting the repo, they are then presented with a form where they fill out the rest of the details - name, description, discord link, status
    • Validate on both the client and the server that the name, description, link are within their character limits
    • Validate that the status is a valid enum value
    • Validate that the discord link is to a thread and not a server invite, or anything else
  • Once submitted, the project is created and viewable by the public.
    • Existing auth tokens in the DB are immediately invalidated by the server upon creation

The page also allows filtering by skill:

• Works similar to filtering in Filtering Tech Spec #111

Updating and deleting a project is done on the specific project's page itself, if you are also the owner.

• Deleting a project requires confirmation by typing in the repo name, similar to deleting a repo on github

When viewing a project, we show:

• Project name
• Project description
• Username of owner
• Link to discord thread/post for discussion
  • Link opens in new tab
  • If you replace https:// in a link with discord://, it'll open in the discord client. Example
• Link to GitHub Repo
  • Link opens in new tab
• Project status

APIs

interface ClientProject {
  name: string;
  description: string;
  repo_full_name: string;
  discussion_link: string;
  status: string;
  owner: string;
}

• POST /api/auth/github
  • Authenticates through GitHub for project creation
  • Request Body:
    • code: string the github oauth code used to generate the access token
• GET /api/projects
  • Lists projects
  • Request Params:
    • skills: string[] the skills to filter projects by
  • Response Body: ClientProject[]
• GET /api/projects/:id
  • Gets a specific project
  • Response Body: ClientProject
• POST /api/projects
  • Creates a new project
  • Request Body:
    • name: string the project name
    • description: string the project description
    • repo_id the id of the chosen repo (ownership validated on backend)
    • discussion_link link to discord discussion
    • status the project status
  • Response Body: ClientProject (the created project)
• PATCH /api/projects/:id
  • Updates an existing owned project
  • Request Body:
    • name: string (optional) the project name
    • description: string (optional) the project description
    • discussion_link (optional) link to discord discussion
    • status (optional) the project status
  • Response Body: ClientProject (the updated project)
• DELETE /api/projects/:id
  • Deletes an existing owned project

Security/Privacy

We'll be following the Principle of Least Privilege when users authenticate with GitHub through us. Meaning, we ask only for the permissions we need - in this case, just read access to public repositories.

When they authenticate with GitHub OAuth, we will only ask for the following scopes:

• read:user (to get the user's github ID)
• public_repo

Access tokens are configured to last only for 30 minutes, and are encrypted when stored in the database.

Project page / viewing is not gated by authentication.

Testing

GitHub Oauth / GitHub API calls will have to be mocked, as we cannot / should not be making real requests for GitHub data as part of tests.

Otherwise, tests will follow the standard pattern of jest acceptance tests for the backend, and cypress e2e tests on the frontend.

Open Questions

No response

Deployment

No response

[Caleb-Cohen]

Great write up!

The page also allows filtering by skill

How will skills be assigned to a project?

Auth tokens are persisted to a DB with an expiration time (enforced both by DB as well as by GitHub App config)

Why do we need to double enforce this?

Edge case: What happens if two people are owners/organization members of the same repo. Could they add the same project twice?

[MainlyColors]

On caleb's edge case, can we allow a project to be tied to multiple owners and those owners all be listed in the UI.

I'm thinking in the case of a project being abandoned by the original creator but someone wants to keep it going.

Implementation wise we could allow the first creator to assign more people but that seems like an anti-pattern. I also thought of if there is a way through the GitHub api to acknowledge additional contributors and list them on the project.

[MainlyColors]

Looked through the spec and its pretty extensive. I have nothing else to add or comment on so LGTM 👍

[jmoldyvan]

I don't think I saw this, are the projects going to be posted up on the board page indefinitely? (Only being able to be taken down by the original creator? ) Additionally, would it be possible to switch ownership of a project if an owner decides to step down?