Skip to content

Home

Jump to bottom
Tessa Thornberry edited this page May 16, 2023 · 23 revisions

Last edit May 15th, 2023

Compass Logo

Welcome to the Compass GitHub Wiki!

Compass is a civic app we are building for the San Francisco Unified School District. The app seeks to assist Teachers with setting and tracking goals for students with disabilities.

Report Bug · Request Feature

Table of Contents
  1. About The Project
  2. Getting Started
  3. Fine Tuning Your Code
  4. Resources

About The Project

Hello, Engineers seeking to contribute to the Compass app! This Wiki is set up to guide you on how to contribute to the repo, and will hopefully answer a few of your questions as to what phase the project is in and how to adopt issues and build out components. This wiki will be updated when possible, revision date noted at the top of the Wiki.

Project Overview

Project Compass is a web app designed to make it simple/easier for Case Managers and Para-educators in a school district to set and record IEP (Individual Educational Plan) data for students with disabilities, based on the initial out-of-app IEP goals that The Case Managers and the student’s stakeholders (usually parents and any specialists) agree upon annually.

Historically, Case Managers (CM's) would use non-specific software like spreadsheets, passing the IEP activities on to the Para-educators (Paras) in the form of verbal guidance and printouts. The Paras would then use the CM's guidance to have set activities with the students, reporting back on the student's progress when they could. While handling the IEP data collection this way works okay, not only is challenging to communicate and adapt to situations like absences and progress hiccups, a CM's and Para's schedules might not match up often during the day, and sometimes a Para or CM could have a challenging class and not have the time or attention available to collect activity data easily.

The Compass app seeks to make CM's setup of the data collection activities straightforward, but most importantly seeks to make the data collection for the Paras fast and simple for their students' activities. After the data is collected by Paras via Compass, the app seeks to visualize that data in order for the CM to review so that they can adjust the activities for the student and compose reports for the stakeholders. You can learn more about it at the project’s source of truth

(back to top)

Current Teams

Compass is split up into five teams, though we currently all meet together weekly to update all teams on progress. Most teams also have a separate meeting during the week. You can find out more on our Slack, which you can join on our site here

The teams are:

  • Groups 1 - 3 - the project is currently split up into the different views our app will present:
    • Group 1: The Case Manager View - A web app with a browser-first view, for the setup of the Caseload:
      • Students and their IEPs. (The students are unique to the Case Manager for that school year)
      • Para-educators the Case Manager assigns to data collection for a student on the Caseload (Some Paras assist more than one CM)
    • Group 2: The Para-educator View - A web app with a mobile-first view, for the Para to collect data
    • Group 3: The Data Visualization - Graphs and charts for the CM View to visualize the collected data
  • Design Team: Handling the styling and visual layout of the different parts of the app
  • Tech Team (Us!): Programming and deploying the app!

Current Project Status

We are currently on the tail end of the design phase, and the Design Team and Project Management teams are deciding what components are needed and how the app should look and flow.

Current Development Phase

The MVP (Minimum Viable Product) for the app is Group 1's work: the Case Manager Initial View. The Para view and Data Visualization view will inform how we set that up, but they are not a necessary part of coding the MVP. Currently, we are writing up new issues in the GitHub Projects board for Compass, and self-assigning them. We are currently working on any components we are sure will be needed, and displaying them in the Case Manager Dashboard file as React Components.

Tech Stack

  • TypeScript
  • React
  • Next
  • tRPC
  • Node
  • PostgreSQL
  • Zapatos
  • Docker (optional)
  • Ava (for back-end testing)

(back to top)

Getting Started

Please use the Repo's README to handle installation. You must contact a team member on Slack on our proj-compass-tech channel to get Auth working, but can do work without that step if you change your url after running "npm run dev" to localhost:3000/cmDashboard, but without logging in you will get Auth errors and will not be able to use the user flows like adding students or staff without hardcoding a CM user_id in your frontend component.

Special Note Regarding Auth

If your Auth worked and then suddenly it does not, it may be that the cookies in your browser are not reflecting the current Auth correctly. This will especially be the case if you migrated the database since the last time you signed in! You can enter the following command into your browser, which will direct you to the cookies for localhost so you can clear just them.

chrome://settings/content/all?searchSubpage=localhost

Using GitHub Issues

Our Projects board is here: Compass Project Board

The Projects board contains issues for the Eng Team as well as other Compass teams, like the Design Team. Eng team issues are discerned by the ending "[ENG]" in their names, and/or the green "engineering" label. You can add issues to the "Todo" list as they become obvious from meetings and discussions of the app. For now, we are adding issues for the MVP (The Case Manager View), but you are welcome to add issues for the Para View and Data Visualization flow to the "Blocked/On Hold" list.

  • Try to be clear in describing the issue you are creating, and include any steps you think need to be taken into consideration. (Feel free to use markdown language to create bullet points and checkboxes. Include diagrams where possible - you can copy/paste an image into a comment and GitHub will create a link for it.
  • Try to break down issues into components that can be built within 1-2 week sprints
  • You convert a drafted issue into an issue by clicking "Convert to Issue" once you have clicked into your draft, in the menu on the right.
  • You can self-assign an issue by clicking "add Assignees" on the upper right menu once you are in an issue. (You will not see this option in a draft)
  • Please try to have 2-3 people per issue and pair program/otherwise work with your fellow engineers. This is how we learn and support each other and also how we get the work done.

Adding Components

  • File structure - src Most files we will be using are in the src folder:
    • pages (frontend URLs) The components we will be building are going to display in the components in the "pages" folder. In Next.js, the pages folder creates the URLs to which users navigate. Most of the Case Manager View components or navigation to them will render via the "pages/cmDashboard.tsx" file
    • Components (frontend component builds) Most of the components that render into the different views and the user-action handler functions will "live" in the "components" folder. For the MVP (CM View), these will be in the "components/case_manager" folder.
      • As with React, you can pass props, including functions, but passing props in TypeScript and with Next.js has to be done with interfaces and deconstructed, like:

** Parent Component **

return (
<div>
  <ThisSpecificForm onSubmit={handleSubmit} title={title} />
</div>

** Child component **


interface Props {
  title: string;
  onSubmit: (event: React.FormEvent<HTMLFormElement>) => void;
}

const ThisSpecificForm = ({ title, onSubmit }: Props) => {
  return (...)
}

export default ThisSpecificForm;
  • File structure - src (cont.)
    • Backend
      • db/migrations/1_initial-migrations.sql The tables we will be using in our database can be added to and altered via the schema in this file. If you are changing the tables in the database, edit these files, and then remember to migrate your local database(npm run db:reset).
      • Routers
        • The asynchronous database queries are written here in Kysely. These files will be where you write your back-end functions.
        • Please write a test or two in another file in "routers", named "myfilename.test.ts" (changeout "myfilename" with your back-end filename). See the ava docs for reference or review the other already-built tests in the "routers" folder to see how we are doing them. Run your tests using the npm run test command
    • tRPC queries Client-side queries are created with tRPC in the front-end components and then implemented in Kysely in the "backend/routers" folder files, which turns them into PostgreSQL SQL queries for us.
    • Styles The CSS for this app is still under development, but whatever you'd like to work with, be it a global CSS stylesheet, inline CSS, or tailwindCSS, go for it! Simply understand that less is better right now, since the UX/UI Team is coming up with their solutions and things are in flux, so we are concentrating on the build rather than the styling at this time.
  • Comments: Please use comments to clarify EITHER: what your code is intended to do (though this can be solved with good, clear naming choices), or if there is future work planned and it's not obvious that's the case.

Git Workflow

  • When you open up your app and get it running and have saved any changes on your local branch, be sure to switch to main and pull any recently merge PR's:

git checkout main

git pull origin main

  • Then create and checkout a branch for your own work, and name it something useful, like what you are intending to do with that branch:

git checkout -b newbranchname ("newbranchname" could be something like "create-benchmark-form" or "add-para-invitation")

  • Be sure to SAVE AND COMMIT OFTEN! After any significant addition or edit!

git add . (or specify the additions you want by entering git status and then only git add changedfile where "changedfile" is the specific file you want to commit)

git commit (You can use the -m shortcut if you already do, but it apparently removes some of the metadata from your commit, so I am describing the "long form" commit flow)

  • You have to hit 'i' to be able to insert your commit message. Please try to make your commit messages meaningful and generally start with a verb, like "added button to add student form" or "successfully rendered para data from specific cm's staff list".

  • Push esc and then :wq to write/quit

  • After NO MORE THAN 250 lines of code + editing (hopefully much less) do a Pull Request (see below)

  • BEFORE your PR, you are going to want to run the linters to pass the checks we have set up on GitHub. This doesn't affect your code's functionality, but it makes it consistent with the code base and thus easier to read.

Submitting Pull Requests

  • Push to your branch in GitHub (git push origin mybranchname)
  • Open a pull request and use the balloon-with-upward-arrow icon to link to the issue
  • Submit the Pull Request
  • Assign 1-2 team members to review the PR
  • Follow up on comments, run any linters, and push committed edited code to your branch on GitHub
  • After approval, squash and merge your PR
  • Delete branch

Code Review Process

  • If you are doing a code review for another engineer, then before you start, pull and merge all code from main so that your repo is up to date, correct any merge conflicts, and save/add/commit. Then pull their Pull Request locally and see what conflicts it might have with the main repo, and run it before you look at the code to be sure there are no breaks in the functionality of the PR.

  • You can pull a PR locally by being in your main branch and typing:

    git fetch --all

    git checkout branchname (where branchname is the PR branchname)

  • Review the code for its clarity, any redundancy, good, understandable names for functions and components, and naming conventions.

  • In order to put your comments in GitHub for the PR owner to review, go to the PR in GitHub and click "Add your review". Hover over the code in question until the blue "+" sign appears, and add your comments. Feel free to distinguish between must-have and would-be-nice changes.

  • Once the PR owner has corrected any must-have changes, approve the PR.

(back to top)

Fine Tuning Your Code

Naming Conventions

Try to name your functions and components well. It's better to have a long, specifically descriptive name than a short-and-sweet name that is super generic.

  • Frontend React Components
    • PascalCase
  • Frontend handler functions
    • where the function is defined, you can name it "handleAction" where "Action" is replaced with the specific action of that function.
    • When passed as a prop, it is passed with the term "on" instead of "handle", like "onAction". See more here

<Component onAction={handleAction} />

  • Frontend "pages" URLs
    • camelCase for folders and files
    • snake_case for specific user/student pages, to align with the database property keys
  • Backend Db PostgreSQL schema
    • snake_case for property keys and table names
      • additionally, table names: we are going with the singular, e.g. "user" "student"
  • tRPC functions
    • camelCase
      • try to make these descriptive and based on the action, like get, post, update, etc.

Testing

When you are building components that interact with the back-end, please write a test or two in another file in "routers", named "myfilename.test.ts" (changeout "myfilename" with your back-end filename). See the ava docs for reference or review the other already-built tests in the "routers" folder to see how we are doing them.

Using Linters

Before you push your code up to your branch in GitHub, be sure to run the linter. Our app is built with eslint and prettier, for clear easy-to-read code. Assuming you have already installed these, once you are ready to push your code up, run:

prettier --write .

You can then check to see that your code has all formatted with the command:

prettier --check .

If your code passes this check, it is ready to push to your branch in GitHub!

CSS Options

You can use any kind of CSS for now, whether it be inline, tailwindCSS, or using the global CSS stylesheets in the "src/styles" folder. Simply try to stick with the UX/UI team's current styles as much as possible and don't do too much flexbox or grid work that we might have to undo later. Most of the styling will take place later after we have built most of the components and the UX/UI Team has come to an agreement on the optimal mix of styling for the elements.

(back to top)

Resources

Significant Links

Glossary Of Terms

The terms below are commonly used in the app docs. For the purpose of Compass, we have established these definitions of these words for our app. Please note that these terms may be easily confused due to conflicts in meaning from earlier docs and from external sources. For the purpose of this app, go with these meanings.

Case Manager/CM: The teachers who set up the Compass app and assign Benchmarks to the Paras in their Caseloads. They usually have a mix of students, including students who need extra support. These latter students have IEPs.

Para-educator/Para: A Para-educator is a staff member assisting the IEP students on behalf of the Case Manager. Paras sometimes have specialties and can assist different Case Managers. The Paras sit down with the students to have them do the activities on the Benchmarks and use the Compass app to collect the data from those student activities/Benchmarks.

IEP: Individual Educational Plan. This is an annual Plan built with a student's stakeholders (usually the CM, parents, and specialists) on the same date for that student every year. The stakeholders gather to assess the student's current needs and areas of growth and agree on goals to help the student work on those areas.

Goal: Also called "Annual Goal," a Goal is set and tracked by the Case Manager outside of the Compass app. These goals are put into language that is NOT activity-based language, like "Get student up to 5th-grade reading level."

Benchmark: Also called "Task," "Sub-Goal," and "Short-term Objective," a Benchmark is a student activity or action that Paras collect data on with the Compass app to track student progress towards a goal. Benchmarks are distinguished by being an activity or occurrence, like "Have student complete 5 sentences with minimal assistance with 80% accuracy in 4 out of 5 trials." The main way to remember how to distinguish between a Goal and a Benchmark is to ask yourself "Is this an actual activity or action?" If the answer is yes, it is a Benchmark. The Case Manager decides the minimum number of Trials/Data Collection activities for each Benchmark, and regardless of how many times data has been collected on a Benchmark, decides when that Benchmark is "complete" and can be archived.

Trial: A single occurrence of a Benchmark activity for the purposes of data collection, like one instance of the Para sitting down with the student to fill out a math or English worksheet. Paras collect data on Benchmarks via trials.

Caseload: The Case Manager's students who have IEPs, and the Paras who help them.

(back to top)

Clone this wiki locally