a99 Final Project

DUE: 2022-04-30T19:00:00-5:00 (End of Exam Period)

GitHub Classroom Assignment Invite: [REDACTED]

UPDATE 2022-02-17: You don’t need to accept this assignment since you are already assigned to teams. So, there is not assignment invite link for a99.

General final project issues and questions: https://github.com/comp426-2022-spring/a99

Specific issues should be addressed with your assigned instructional staff member via issues inside your team’s assignment repository.

NOTE: You are all each individually responsible for submitting a final self- and team-assessment in addition to your team’s submission of the final project. Instructions will be available for that on the assignment page under FINAL.

Overview

As a small team, you will create an app that relates to providing, managing, collecting, or tracking information related to a public health event, phenomenon, or policy. This can take many forms, so here are a few ideas of the kind of app we are looking for:

  • COVID-19 info dashboard
  • Annual flu tracking app
  • Disability advocacy platform
  • Tracking app/portal for accessing mental health resources and information
  • Emergengy/disaster management provider/public portal
  • Disease outbreak tracking/prediction map
  • Personal health information management app
  • Public health historical information/data preservation and archiving system
  • Portable universal electronic health record (EHR) system*

* This is sort of a reach for the stars type of idea. It’s entirely possible that someone may figure this problem out and develop a system or protocol for this that has the potential for wide adoption and there are a lot of really smart people working on it, BUT NO ONE HAS DONE IT YET. So, now is your chance to invent a thing that will revolutionize health care records management while also being compliant with personal health records laws in all of the places it may be used and does not face resistance from existing proprietary EHR vendors, etc. You can do it. I believe in you.

Your team will be responsible for scoping, planning, and designing an app or system like one of those listed above, and also programming a working prototype.

The app should be fully documented, including setup instructions, full API documentation, and user instructions, as well as your planning workflow (notes, GitHub Project boards, discussions archives, etc.).

Your team will create a <= 3-minute video describing your app to present to the class about your app. This can be a very basic walkthrough, or a description/presentation of features/use cases, or something else. Be creative. Think of it as an opportunity to hone your ability to pitch an idea that you have in prototype (because that is what it is).

Phases

Phase 1: Scoping and Planning

In the planning phase, your team should start with brainstorming ideas and begin to develop an idea of what you want to create an app to do, what is feasible, and what you need to know to proceed. Your team will also want to think about task and labor structure: who is going to do what? Who keeps track of what? Who works on what aspects? Who is good at what?

When? Ideally your team will begin this process by the last week in February.

What to do? Set up a Project board on GitHub and assign it to your team so that you can manage brainstorming ideas and transition into designing and documenting. Choose a license. Use the README to document general information about the project and instructions to install or run it in whatever state it happens to be throughout the project.

Phase 2: Designing and documenting

In this phase, your team should begin sketching out the major parts of the system or app and looking at similar or related concepts to understand the state of the art. This is a good time to figure out how someone else is approaching a certain problem related to your app or system. Your team should use this information to then extend, adapt, and improve existing approaches, or make a radical departure and try something entirely new.

When? In the beginning of March, your team should be pulling together a system design and documenting it in your team’s Project board and repository. During spring break, step back from the project and incubate the ideas and designs/sketches/schematics/plans/etc. that you have been working with. When we return from spring break, your team should start working on programming base components, laying out package structure, and making decisions about how different parts are articulated together.

What? Keep notes and documentation in whatever form it takes in your teams’s GH repo. Use the project management tools in GitHub to keep track of things. Create a basic repository structure that your team can fork to begin working on components and features.

Phase 3: Prototyping and Pitch

In the last phase of this project, your team will pull together a working prototype. It does not have to be complete or polished: it just has to do the things that you want it to do in some form. You should also be cleaning up your documentation and moving it from documenting what was planned to documenting what is being executed in the prototype. This means noting what is currently working and what is not yet working or may work in a later iteration the design.

Your team will also be working on a three-minute-or-less (<= 3 min) pitch video to show in one of the sessions in the last several sessions of class (21 and 26 April).

When? At the beginning of April, your team should begin pulling a prototype together, settling into a set of prototype version features, and debugging it. Your team should be consolidating, organizing, cleaning-up, and clarifying documentation at this time. Your team should also be organizing the package that will contain all of the parts of your app and its documentation as a prototype release.

By mid-April, your team needs to be mostly debugging and working through changes to create your prototype release. During the third week in April, your team needs to create a video and make a pull request to get it in the queue to present during the last two sessions of class.

What? Integrate new features using pull requests to your project repository on GitHub. Move cards from “In progress” to “Review” or “Finished” in your project plan. Work on documentation. Organize the software package. Prepare a prototype release. Make a video demo.

Deliverables

A GitHub repository containing your code and documentation and a prototype release package. Your project should take the form of a Node package, with all of the attendant items associated with that. The following three script commands should work in your package:

  1. npm install - Install dependencies for your package.
  2. npm test - Start app, check that everything can run, and then stop app.
  3. npm run - Command to bring up all parts of the app/system’s server scripts.

Your team is responsible for incorporating the following specifications and deliverables into your final project:

  1. Back-end specifications
    1. API built on whatever framework you choose. You can build an API that interacts with other APIs as well in order to integrate them.
    2. API root endpoint at http://HOST/app/.
    3. Should create (if nonexistent) and interact with a database of users and interactions (this can be logs, even). These can be separate databases for different microservices or separate tables in one database. It is up to your team’s decisions.
    4. Database can be of any type you choose.
  2. Front-end specifications
    1. Give users the ability to register an account, update their information, see their information somewhere, and delete their account.
    2. Interactions with the front end should be logged in a database.
  3. Database specifications
    1. User database - registration details (username, email address, etc.)
    2. Interaction database - details of user interactions (login history, access logs, etc.)
  4. Documentation
    1. License documenation - Choose a license and include it in the repository just like we have been.
    2. README.md file with basic descriptiong, installation requirements/instructions, dependency list, run instructions
    3. /docs/ directory containing full documentation of every available API endpoint that you create for your app. This directory shoud also house an archive of your planning documentation.
    4. Code comments (preferably referring to the documentation)
    5. User instructions in the interface
  5. Demo video
    1. In order to get credit for this, add a row to the table in the README here and make a pull request: https://github.com/comp426-2022-spring/a99-demos/edit/main/README.md
  6. Self/group evaluation (Individual group members: this is part of the final exam for the course.)

Logistics

You will be working in a small team (up to 5 people) for the final project assignment.

Your team will be responsible for planning the project, determining roles, and then employing a collaborative workflow to build out your project. Different people will be interested in different parts of the project. Not everyone has to do the same things, nor should they.

Your team will also be responsible for meeting with an LA to check in weekly over the next few weeks to help you make progress through the assignment.

The project teams will be managed through GitHub classroom. Teams are created/assigned when you accept the assignment. So, if you have a group of people you want to work with, the best way to set this up is to meet and accept the assignment at the same time so that you can choose the team together. GH classroom is configured to cut off teams at 5 people.

Using collaboration features on GitHub

The initial README.md file in your team’s GitHub repo has some beginning steps instructions in it. It is replicated below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
# STOP!

Accept the final assignment a99 invite here: https://classroom.github.com/a/IbwBAA8J

If you have done that already, then proceed.
You MUST accept the assignment via the link above before you do ANYTHING else.

# a99 Final Project

## Summary 

COMP426 final project template repository.
All your code and documentation goes here.
Change this text to be a brief description of your final project.
Put the name of your project in the header above.
You will change everything below to be the main technical documentation, as outlined below.

## First steps

Other steps that you will need to take after your team has accepted the assignment:

1. Choose a license and update the LICENSE file accordingly. 
2. Edit this README.md file and use it as the main location of your technical documentation with links out to information contained under `/docs/`.
3. Create a `/docs/` directory for more elaborate documentation of your API, planning notes, etc.
4. Make sure that all of your team members have access to the repository as administrators.
5. Create a project under the **Projects** tab. Use this to manage your planning. Create a To-do list, etc. Explore the tools available and user them to manage your project.
7. Assign team roles and include a listing of those roles in this README.md file or in another file under `/docs/`.
8. Then put your entire development workflow in this repository.
9. Use **Pull requests** to propose changes and incorporate them into your code from various team members. 
10. Use **Issues** to identify and track bugs and also to communicate about various aspects of the project.

## Team mangement

Plan to meet with your team ASAP.
Talk through identifying roles within your team.

Try to figure out what each of you are good at/enjoy doing and try to work out roles that incorporate that.

Some basic roles you will want to consider:

1. A review manager - someone to review pull requests and merge or reject them and manage the related discussions
2. A plan manager - someone to keep an eye on the overall plan and keep the project tab/to-do list up to date
3. A documentation manager - someone to keep the documentation in order and identify what is missing and needs to be documented
4. A release manager - someone to manage the packaging and release process for your prototype package
5. A project manager - someone keeping track of all the moving parts and make sure that everything that needs to happen is happening.
5. Roles for team members to take charge or different parts of the project. Possible roles:
    1. Front end lead
    2. Back end lead
    3. Database lead
    4. Design lead
    5. Etc.

You will notice that there are more roles than people in your group.
That is because you will all be doing a hybrid job of managing a thing while working on other things.

## Check in with instructional staff

Schedule a few times throughout the rest of the semester for your team to check-in with your assigned instructional staff member during their scheduled office hours. 

## Assignment instructions

And that is about all you need to get started.

All the rest of the assignment instructions are available at: https://comp426.johndmart.in/a/99

Good skill and be creative!

Pull requests

Your team must use the fork and pull requests feature in GitHub to manage contributions, changes, and discussions about your code and documentation. This makes everything a lot easier and you are less likely to overwrite someone elses work, run into merge conflicts, etc. It is a built-in collaborative workflow.

Issues

Additionally, use the issues feature to manage bug-fixing and feature discussions. It makes things easier to keep track of. It also helps the instructional staff help you because there will be context and documentation related to your project that we can review when we meet with your team during office hours.

Projects

There is a “Projects” tab available in your team repo. Create a project board in the class GH organization and attach it to your team.

This is a great place to organize your work rather than relying on email, Google docs, Groupme, etc. This also allows us (the instructional staff) to see how your project is progressing and to help you with questions and issues because it will give us context.

License your work

In addition to the README above, you will find a LICENSE file in your team’s repo. This is provided as a placeholder so that you may replace it with the license of your choice.

The placeholder file contains some information about choosing a license and how to include it in your repository. Read through the links in this file and try out the decision tools to prepare for having a discussion with your team about licensing.

Make sure that the license specified in your Node package.json file matches that in your LICENSE file.

You will want to change the text in this file to be the text of the license for your project.

Information about choosing a license can be found here:

[Licensing a repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository)

[Choose an open source license](https://choosealicense.com/)

[SPDX License List](https://spdx.org/licenses/)

[Browse Software Licenses and Summaries](https://tldrlegal.com/licenses/browse)

[How to choose a license for your own work](https://www.gnu.org/licenses/license-recommendations.en.html) - GNU Operating System

[Public license selector](https://ufal.github.io/public-license-selector/) - Institute of Formal and Applied Linguistics (ÚFAL), Faculty of Mathematics and Physics, Charles University

Expectations

The expectations for this project is something along the lines of a working prototype. It does not have to be beautiful, it just has to work for the most part. And it does not have to be feature rich, it just has to do some pretty basic things.

I expect and encourage inter-team collaboration as well. If there is something that your team finds useful: create a discussion in our class organization about it!

The repositories for this project will be created under the course organization as open source. This is intentional to encourage you to share things and learn from what your peers are doing.

Finally, be creative!

This doesn’t mean that what you build has to be earth-shattering. It can be whatever your team wants it to be.

Public health as focus

I have suggested building apps or systems for this project that relate to public health for several reasons, enumerated below.

  1. We are in the midst of an ongoing public health emergency. Focusing on what we can do in this context should help us better understand what is happening and how we can work within it/survive it.
  2. Public health is and has been a very hot field in recent years/decades in the tech sector.
  3. Public health research is increasingly a field that depends on computation, data, and information management methods. There is A LOT of work to be done in this area.
  4. Public health is a real, meaningful, and crucial area of thought and work for the current iteration of the human project. We need a wide variety of engagement with this area.
  5. SAVE THE WORLD. Or, at least try. And, in the process, maybe find a way to make something at least incrementally better.

You’ll have your whole careers to do boring stuff just because someone tells you or to be the someone telling someone to do boring stuff. I’m giving you an opportunity to do something that is engaging, timely, and addresses problems that we are experiencing in real time. We learn better when we are engaged in meaningful action that co-creates new things/knowledge/ways of knowing/ways of doing.

So, BE CREATIVE, and do interesting things!