mesh-research/pilcrow

A web application for Collaborative Community Review

Pilcrow

Documentation • Demo • Discussions • Bugs • Feature Requests & Suggestions

About Pilcrow

Pilcrow is a web application designed to support the Collaborative Community Review (CCR) peer-review process.

Collaborative Community Review is a healthier, more effective way to review and develop work for publication.

Traditional peer review at academic journals serves a gatekeeping role, determining whether a piece is publishable or not; this decision comes after the piece is nearly complete. This type of peer review practice often proves hostile to new ideas, unproven authors, and unfamiliar audiences. The process can even be traumatic for those involved. The PPJ is changing that with transparency, community engagement, and ongoing developmental conversations.

CCR nurtures new ideas by supporting pieces through their development, creating supportive experiences for authors and audiences. The goal of this review process is to both prepare pieces for publication and improve them in those preparations. CCR is structured to encourage peer engagement rooted in trust and a shared commitment to improving the work through candid and collegial feedback. The review process is formative in a twofold sense:

1. The Piece: CCR helps shape the work so that it might effectively enrich public life, and

2. The People: CCR cultivates habits of responsiveness and collegiality among participants.

Because the review process is formative for the piece and the people involved, each participant must enter into it willing to learn and be transformed by the process itself.

To read more about the CCR process, visit the Public Philosophy Journal's page describing the process

Installation

Instructions for deploying Pilcrow on your own server can be found in our documentation

Contributing

See our contribution documentation for help getting started with a Pilcrow development environment. Feel free to reach out to the core team via GitHub Discussions

Pilcrow welcomes and recognizes the contributions of all contributors to our project, not just code. You can see the full list of contributors on our documentation site.

Pilcrow Wiki - https://github.com/MESH-Research/Pilcrow/wiki

• An opinionated application
• Pilcrow Links
• Style Guide

pilcrow's Issues

Setup documentation framework.

Problem/Why

We don't currently have a place for platform documentation to reside with code.

---

Goal/What

Create/Integrate a documentation platform for documentation about platform features, uses, tutorials, and guides to live alongside the codebase.

Solution/How

Use Vuepress to create the documentation and Github Actions/TravisCI to publish the documentation to github pages or netlify.

---

To Do

• Setup Vuepress
• Add Lando configs for documentation
• Create CI configuration to compile and publish.

Review Checklist

How to test:

1. Goto: https://mesh-research.github.io/CCR/
2. Click on, for example: Guide in the top navbar.
3. At the bottom, click the link to Edit this Page
4. Make some edits to the page (something trivial, but that you'll notice)
5. At the bottom of the GitHub page:
   1. Enter docs: testing documentation updates as the commit message (to follow our commit guidelines)
   2. Leave the extended description blank
   3. Leave the radio button on Commit directly to development (this type of edit should usually be a pull request, but for testing this card, this is just simpler)
   4. Click Commit Changes
6. Wait a few minutes for the build and deployment to complete.
7. Go back to https://mesh-research.github.io/CCR/ and confirm that your change is now there.

• Documentation is available online for the development branch
• Documentation builds correctly on pushes to the development branch

Trello Source: https://trello.com/c/WlaLxOjt

Setup the connection between Apollo Client and Lighthouse

Problem/Why

There is currently no way for the frontend and backend to communicate with one another on CCR.

---

Goal/What

The frontend and backend applications need a way to communicate with each other. Connecting Apollo Client and Lighthouse alleviates the problem. Ensure successful data transfer between the frontend and backend apps.

---

Solution/How

---

To Do

Review Checklist

Attachments

• Is child to System User Authentication

Trello Source: https://trello.com/c/kYJzyych

Authentication - Internal Credentials

Problem/Why

There is currently no way to identify users in the system. There is also no way for users to authenticate using their email address and a custom password.

---

Goal/What

Create a system that allows users to authenticate. Its sign in functionality should accept email and custom password pairs. Verify that the email exists in the system and that the password typed in matches that email.

---

Solution/How

Create data structures in GraphQL to represent users.

Write backend code to create necessary components/models for representing a user and its credentials.

Write front-end code to send credentials to backend.

Write front-end code to handle the response from the backend.

Accessibility Checklist

Review Checklist

Acceptance Criteria

• user can type in an email address and password
• The system will find the email address in the database and verify the password submitted matches

Attachments

• Is child to System User Authentication
• Is blocked by Setup the connection between Apollo Client and Lighthouse
• Is blocked by Setup Sanctum on the existing backend application
• Is blocked by Implement Apollo Client

Trello Source: https://trello.com/c/qmezfF2g

Implement User Roles in Database

Problem/Why

There is no framework in place that defines user roles within CCR. There is a chance the current understanding of user roles in the attached spreadsheet may be outdated. As of now, the current understanding is that there is a role relative to the application as a whole (application administrator), roles relative to publications (publication administrator, editor), and roles relative to submissions (review coordinator, reviewer, submitter). These all have very different concerns with regard to functionality and security.

---

Goal/What

Double-check with team and stakeholders that the current understanding of roles is correct. Develop a framework to define user roles and associate them with users.

---

Solution/How

Just to be safe, consult with team and stakeholders (again) to verify that the currently defined roles are correct.

Design a database schema for user roles. This will likely involve creating additional tables: a user_roles_publications table for roles relative to publications, and a user_roles_submissions for roles relative to submissions. Because these roles have a many-to-many relationship with publications, submissions, and users, it will be necessary to create linking tables between these tables and the existing table for users, publications, and submissions.

Application Administrator is currently the only role relative to the application with a one-to-one relationship with users. It may not be necessary to create a separate table for this role.

Install the third-party package spatie/laravel-permissions to establish the scaffolding for user roles and permissions by role.

Create migrations to persist roles to the database.

Write tests to ensure functionality works.

To Do

• Determine that an Application Administrator would be best suited as a "Super User" https://spatie.be/docs/laravel-permission/v3/basic-usage/super-admin
• Hold short meeting to discuss currently defined user roles Discuss currently defined user roles via message
• Write migrations for creating the necessary tables for user roles
• Write migrations for populating the necessary data for user roles

Review Checklist

Attachments

• CCR Actions by Role
• Is child to User Roles and Permissions

Trello Source: https://trello.com/c/BAEsAQBu

Incorrect label on login page

The field label for username is "Username of Password" and should be "Username or Email"

Prepare for January 4th Meeting with Dean Long

Problem/Why

There are still uncertainties and questions surrounding language and expectations documented in the grant and of expectations that Dean Long might have for CCR. The current understanding of the intended review process is not well understood and may not be able to be better defined any time soon.

---

Goal/What

Resolve uncertainties and ask questions about the grant, CCR, and (potentially) CCR's review process as it pertains to FPR.

---

Solution/How

Research and gather a series of questions for Dean Long. Consult with team for feedback prior to the meeting. Arrange an agenda to present for the meeting.

---

To Do

• Research, gather, and document questions in a Google Doc
• Consult all team members for feedback, when available
• Arrange meeting agenda

Attachments

• FULL PROPOSAL Long Mellon PPJ 2020-01-30 FINAL.pdf

Trello Source: https://trello.com/c/oZqpthC4

a user should be able to maintain a profile

A user should be able to login

Draft Presentation of Application Understandings

Problem/Why

There are elements and relationships of CCR that may not be fully understood or illustrated among all members of our team. The team's understanding of how these elements are meant to work might not be fully aligned with the expectations of stake holders like Chris.

---

Goal/What

Create a presentation for Chris to evaluate assumptions about CCR against his expectations.

---

Solution/How

Create a first draft compilation of descriptions and diagrams of workflows and relationships between various entities as we currently understand them.

---

Review Questions

• Did the tools selected to achieve this goal work well? Why or why not?
• Did the materials in the presentation communicate concepts clearly?
• What were the most challenging aspects of creating the presentation?
• Were there any surprises?
• How should we proceed with the next iteration if we later discover there were concepts missing from this presentation?

Accessibility Checklist

• All language and terminology is consistent and easy to understand
• Diagrams and imagery are easy to follow and comprehend
• The foreground appearance of readable elements is legible and contrasts well against background colors
• It is not necessary to zoom or adjust the browser to view the entirety of diagrams and imagery included

Acceptance Criteria

• The presentation fulfills its purpose by communicating all known person-oriented high-level concepts
• The presentation can be easily shared with as many parties as necessary, not just those who already have access
• As a team member of MESH, I can access the presentation

Attachments

• PowerPoint Presentation

Trello Source: https://trello.com/c/zVx4E4xe

Implement Apollo Client

Problem/Why

Apollo client helps us connect to the backend application which enables data exchange.

---

Goal/What

A working instance of Apollo client with Vue.js.
Ability to execute GraphQL queries, mutations and subscriptions.

---

Solution/How

Apollo client implementation for Vue.js https://www.apollographql.com/docs/react/integrations/integrations/#vue
I

To Do

Review Checklist

Attachments

• Is child to System User Authentication
• Blocks Authentication - Internal Credentials

Trello Source: https://trello.com/c/tYVRMBgk

Password Reset - A user should be able to recover their account.

Problem/Why

A user cannot recover their account if they forget their password.

---

Goal/What

The user should be able to visit a page in the application, enter their email, and have an email sent to them with a link to reset their password. Upon visiting the link, the user should be prompted to enter a new password.

---

Solution/How
Create a Contract to reset password "Illuminate\Contracts\Auth\CanResetPassword" using lando artisan make:contract CanResetPassword
Generate a reset token and update the db with the reset token.

https://laravel.com/docs/8.x/passwords

---

To Do / Acceptance Criteria

• Update Vue templates to handle user interactions for requesting a password reset
• Update backend to handle password reset requests
• Add functionality to backend to send a user a password reset email
• Update Vue templates to submit password resets and handle server responses to password resets
• Add validation for password reset data

Review Checklist

• A user can request a password reset
• The user is sent an email to follow to reset their password.
• The link presents as form to submit a new password
• The password is reset

Accessibility Checklist

• New interactive elements can be accessed solely by keyboard
• New interactive elements are discoverable by a screen reader
• Pages pass axe DevTools accessibility testing

User Submissions by Text Input

Problem/Why

Currently, users cannot create a new submission without uploading a file. This can create an obstacle for submitters who would rather compose or paste text directly into a textarea to submit a manuscript to be reviewed in the application.

Goal/What

Enable a user to be able to paste text into an input, submit it, and have their text saved to the system as a new submission.

Solution/How

Create a form that accepts text for a submission. Write functionality to save the submission in the database and associate the submission to the user as the submitter.

To Do / Acceptance Criteria

• Update backend to accept text for a submission creation
• Create/modify Vue template(s)
• Add PHPUnit testing to verify the submission creation API works as expected

Review Checklist

• A user can create a submission by just pasting text into a textarea
• The resulting submission is saved in the database and assocated with a user

Accessibility Checklist

• The submission form can be used solely by a keyboard
• No new accessibility violations are introduced

Configure unit test CI

Setup CI to run standards and tests

Tests: composer test
standards: composer cs-check

Publication Management - User Role Assignment

Problem/Why

Currently, users cannot be assigned roles at any level by any user. Those roles are defined under the following role categories:

Site-Wide

• Administrator

Publication

• Manager
• Editor

Submission

• Review Coordinator
• Reviewer
• Submitter

---

Goal/What

User roles should be defined in the system to be assigned to users.

Implement functionality for users to assign and modify roles to users by article, publication, or site level. Any user with an assigned role should have access to the same functionality of any other user with the same role.

In theory, assigning users are restricted to assigning other users to roles based on the role category of the assigner. The permissions for user role assignment are as follows:

• Users under the Site-Wide category can assign any user to any role under the Site-Wide, Publication, or Submission categories
• Users under the Publication category can assign any user to any role under the Publication or Submission categories limited to their own Publication only
• Users under the Submission category can assign any user to any role under the Submission category limited to their own Publication only

---

Solution/How

• Create forms to allow authorized users to view and edit user roles
• Control what actions a user can do based on their role

Review Checklist

Accessibility Checklist

Acceptance Criteria

Trello Source: https://trello.com/c/o7hyFgxO

Authentication - External Identity Provider Authentication

Problem/Why

The application requires users to create a new set of credentials. Users may find having to create and manage a new set of credentials for Pilcrow to be cumbersome and may prevent them from using Pilcrow up altogether. Users may be disappointed upon discovering that they are unable to authenticate on Pilcrow using their (for example) Google account.

Goal/What

Implement functionality that allows sign-ins from external accounts (ex: Google, Twitter, Facebook). Users should be able to authenticate with those chosen external identity providers.

Solution/How

• Update Login page template to support external auth
• Use Laravel Socialite to enable external identity provider authentication.
• Necessary backend unit testing has been added
• Necessary frontend unit testing has been added
• Necessary integration testing has been added
• Documentation has been updated to reflect new changes

Review List

• No new color contrast issues are introduced
• Added or changed text has a font size of at least 16px
• Added or changed text uses plain language

Trello Source: https://trello.com/c/Kw9ElgRE

Build docker container for deployment

Possible power ups

When setting up this board, a few power ups were considered. Below is the list and thoughts on each.

Power ups rejected

• Card Mirror - sadly only free for 15 days, so rejected. Allows boards and cards to be linked. https://trello.com/power-ups/59dfb7cfb1f4ceeb9388c6ce/card-mirror-by-placker-
• Hello Epics - track an manage complex projects by grouping cards. Costs money. :( https://trello.com/power-ups/58c85f41d7f012a1879c7b2e/card-relationships-hello-epics

Power ups considered

• Google Drive - connects Trello and Drive. Not sure where we're planning on storing our documents Google or MS. Also, lots of connection warnings because of access we're enabling. Might be worth it. https://trello.com/power-ups/55a5d916446f517774210006/google-drive
• Agile Dashboards by Corrello - provides Burndowns, Burnup, Cycle time, CFD, Slow Cards, custom stats, Agile Metrics and more... Also, has access permission warnings, but might be worth it. https://trello.com/power-ups/568c2b6c7d2758a55ac48c98
• Planyway: Calendar and timeline - I love this one, but I'm not sure we're going to really track anything by date. They have a limited free version. https://trello.com/power-ups/58bd1f9aca72f48c8900574f
• Calendar: similar to Planyway and free. Again, not sure we need it. https://trello.com/power-ups/55a5d917446f517774210011
• Jira Align: provide a more structured agile process. Enables charts. https://trello.com/power-ups/5e3886cd2ae34410748d0d5b/jira-align-
• Agile Story Maps by StoriesOnBoard - modifies how the board looks. Rejected it as I think we may prefer it looking like it currently does. But something to consider if we want to lay out our board differently. https://trello.com/power-ups/5e63a894274699243d1e7f36/agile-story-maps-by-storiesonboard
• Dashio - in beta, another charting power-up with standard warnings. https://trello.com/power-ups/5c697e38e3a0791c604b2d41/dashio
• Miro - a whiteboard platform that works pretty nicely. Standard disclaimers for being a 3rd party plugin. https://trello.com/power-ups/5893c2b56bde057070fbc1b7/miro
• Advanced voting system: uses 1 column as a voting column where any card in there becomes a polling/voting option. https://trello.com/power-ups/5ebf674034d5983bef1cc851/advanced-voting-system
• Card reactions: expand our emoji set https://trello.com/power-ups/5e93caec6161c973f82f2856/card-reactions

Powerups added/trying

• Custom Fields - really like the ability to add fields to the cards. Optional to have them show up on the front of the card. Various types of fields. https://trello.com/power-ups/56d5e249a98895a9797bebb9
• Dependencies - not sure if we want this one. There's all kinds of warnings about what access we're giving to the app. Everyone would have to be on board with it. #PunNotIntended Benefits are: it would let us identify if we have related cards, parent/child relationships, blockers, etc. https://trello.com/power-ups/5cf76de9dd07a8533f281b34
• GitHub - this could link to the github repo that we've set up for the application. I need the developers to take a look and see if you like it. https://trello.com/power-ups/55a5d916446f517774210004

Trello Source: https://trello.com/c/Ke0Mrgj0

Develop User Permissions

Problem/Why

The current understanding of what actions are allowed (permissions) by role in the attached spreadsheet is not fully defined. Attempting to fully define them now (February 2020) is premature considering how early the application currently is in its development. There are currently no permissions formally represented in the system. It is not yet confirmed that permissions, when implemented through spatie/laravel-permissions, will query as expected from the GraphQL endpoint.

---

Goal/What

Define the first permission in the system via migration and write tests to ensure that it is queryable from the GraphQL endpoint.

---

Solution/How

• Write a Laravel migration to add the first test reset passwords of other users
• Write PHPUnit tests for the following:
  • Check that his permission exists
  • Check that the permission is returned on the GraphQL endpoint as expected for a user assigned with this permission
  • Check that the permission is not returned on the GraphQL endpoint for a user not assigned with this permission

---

Review Checklist

• The new permission exists in the permissions table
• PHPUnit tests successfully run locally

Attachments

• CCR Actions by Roles
• Is child to User Roles and Permissions
• Is child to User Roles and Permissions

Trello Source: https://trello.com/c/Np2eCHPM

Add Submissions Section to the Publication Details Page

Problem/Why

While there is a page that exists for displaying an individual publication's details, and this shows a sufficient amount of basic information about the publication, a publication's submissions are not represented on this page.

---

Goal/What

Add a section to the publication details page to show a publication's associated submissions.

---

Solution/How

Design in-browser where and how the new section should appear on this page. Add necessary client and backend code for retrieving submission data related to a publication.

• Add code to retrieve submission data
• Add Submissions section to publication details page
• Add Jest testing to assert that an expected number of submissions appears in this new section
• Add or update to Cypress testing to ensure axe DevTools checks for accessibility issues

---

**Review Checklist **

• Language is clear and understandable
• There are no color contrast issues
• All new and existing tests pass

---

Trello Source: https://trello.com/c/caNwU6wD

Logout icon doesn’t display

Logout icon doesn’t display in the user drop down (only visible when logged in)

Determine Development Stack

Extension Card: https://trello.com/c/fq0UNi6X/50-database

---

Problem/Why
Decide what components will be required for application development

---

Goal/What

To select a stack for the CCR application.

---

Solution/How

Individually investigate options. Present information learned to the team. As a team select the platforms we'd like to use.

---

To Do

• Database alternatives: MySql, Postgres, Firebase, others
• Review Vue UI Kits: Vuetify, BootstrapVue, Quasar

Review Checklist

Attachments

• Architecture Decisions

Trello Source: https://trello.com/c/ot6zelSo

Connect Apollo Client to Lighthouse Subscriptions

Problem/Why

Currently there isn't a way to watch events (an action performed in the app such as updating the user information) in CCR. Subscriptions allow GraphQL clients to observe and receive notifications on events.

---

Goal/What

Ensure successful data transfer between the frontend and backend apps when an event is triggered.

---

Solution/How
A subscription is defined on both the server side and client side just like it is done for queries and mutations.
Add the service provider to config/app.php

'providers' => [
    \Nuwave\Lighthouse\Subscriptions\SubscriptionServiceProvider::class,
],

Install the php pusher library

composer require pusher/pusher-php-server

Define subscriptions in the schema
Docs: https://lighthouse-php.com/master/subscriptions/getting-started.html#setup

---

To Do

• Update providers in app.php to include subscriptions .
• Install php-pusher library using composer.
• Implement two way communication via GraphQL subscriptions.
• Write unit tests to ensure that the subscriptions are triggered when the user information is updated.

Review Checklist

• Updates to the user's data is immediately published to the frontend.

Attachments

• Is child to System User Authentication

Trello Source: https://trello.com/c/gXVZcqWa

coworking on season and sprint release planning

Problem/Why

Describe what is currently wrong from the user's perspective.

---

Goal/What

Describe the intended behavior to address and resolve the problem.

---

Solution/How

Held a meeting on Jan. 4th.

To Do

• Identify the epics for the spring season release
• Create cards for the epics, features, and tasks
• review cards as a team for understanding and clarification
• identify the tasks for first sprint of spring release (6)

Review Checklist

Trello Source: https://trello.com/c/qBvgaYFs

Internal user creation

Problem/Why

Users cannot register an account.

---

Goal/What

Users should be able to create a local account (not including social sign-on).

---

Solution/How

Implement front-end pages and API endpoints to allow a user to register. Input data should be validated on both the front-end and backend and appropriate feedback should be provided to users.

** Schema **

Query {
   userCreate(name: String!, email: String!, password: String!): User!
}

Validation Criteria:

• Name: required
• Email: required, valid email, unique
• Password: required, zxcvbn at least 5 (?)

Password should be validated on both frontend and backend. Live feedback should be provided to users regarding the strength of their password.

Laravel zxcvbn library: https://github.com/olssonm/laravel-zxcvbn

---

Review Checklist

• Users can register an account
• Submitted data is validated properly.
• UI/Flow follows best-practices and provides for excellent User experience.

To Do

• Configure apollo-client to communicate with the laravel API
• Add tests as appropriate

Trello Source: https://trello.com/c/M3LP21fR

Obtain Metadata from PPJ Editorial Team

Problem/Why

The current understanding of what information might be necessary to represented on profiles in CCR.

---

Goal/What

We need to know what information the application should store and which role should have the right to change each field

---

Solution/How

Create a list of fields needed, what information they would contain, and who has edit rights

---

To Do

• Potentially look at other systems, such as Humanities Commons, to see what other data their profiles contain
• Mine the Matrix system to see what is being captured in the current PPJ/FPR system.
• Meet with PPJ Editorial team to learn which fields they would like to have in the application.

Review Checklist

• review the list of fields to verify there aren't duplicates
• review the list of fields to make sure they are able to be implemented
• review the list of fields to make sure they make sense
• review the list of fields to make sure nothing is missing

Trello Source: https://trello.com/c/lo1NZiiX

Wireframe user password reset, lost password views

Problem/Why

Users forget their passwords and need a way to request a password reset.

---

Goal/What

Wireframe the UI for requesting a password reset and resetting the password.

---

Solution/How

Wireframe the views...

---

Acceptance Criteria

• Fields for email/username on lost password form
• Fields for new password and new password confirm on reset password

Review Checklist

• Fields for email/username on lost password form
• Fields for new password and new password confirm on reset password

Trello Source: https://trello.com/c/70OxP7ut

Statistics Reporting and Editorial Workflow Dashboards

Problem/Why

There is defined spec for layout and desired functionality for the dashboard that a user initially sees when authenticated on CCR.

---

Goal/What

Implement statistics/metrics reporting and editorial workflow dashboards in the application.

---

Solution/How

• V2 OPTIONShow publications directly involved in and sorted by recent activity
• SHOWN IN WIREFRAMES FYI, for editors (and review coordinators?) this list will include new submissions needing assignment (https://miro.com/app/board/uXjVO1xqVAo=/)
• V2 OPTION Show options for filtering/sorting by publication, status and users role (e.g. Show submissions i am a...review coordinator for)
• V2 OPTION Highlight submissions that require the user's attention
• V2 OPTION Suggestion: Information density controls
• MOVING THIS TO IT'S OWN TICKET EVENTUALLY Mobile interface suggestions to deal with information density and available real estate concerns.

---

Review Checklist

• Add review notes to the XD docuement.

Trello Source: https://trello.com/c/oATdI1CB

Schema lock file shouldn’t be committed

This file is only used for baking diffs and snapshots, something we don’t do. Since this file changes every time a dev does a migration it changes a lot and pollutes the history.

Develop a Team Charter/Norms Document for CCR

Problem/Why

It would be useful to have a document that has captured the agreed-upon standards for the team to review in the future and for any onboarding of new members. MESH would like to use it too.

---

Goal/What

Review, enhance, and fill out the Teams Norm/Charter document for CCR and lay it out so a blank version could be used as a template for MESH or other projects

---

Solution/How

The team will review in advance of a meeting where we walk through the comments and sections for the attached document.

---

To Do

• Kelly will create a meeting for us all
• Review the attached document (individually) prior to the meeting and provide comments
• Go through the comments (as a team) and identify any additions to the document
• Any expansions of the document template, Kelly will add to the blank template to be shared with MESH

Attachments

• CCR Teams Norm doc

Trello Source: https://trello.com/c/S7VFZeFY

Prepare for Meeting with Dean Long

We're meeting with Chris on Dec. 7th. We need an agenda and be prepared with whatever we intend to talk about or show.

Trello Source: https://trello.com/c/2DpGn5yk

Utility of document oriented database

Previous Card: https://trello.com/c/ot6zelSo/48-determine-development-stack

---

Problem/Why

The development team isn't entirely sure where a document store might be useful to the project, but it seems worth investigating.

---

Goal/What

Produce research and some opinions to report to the team so that we can make a decision regarding the utility/benefit of adding a document store to the project.

---

**Solution/How
Added notes on research to the CCR architecture document:
https://docs.google.com/document/d/15qTFcvSox0ZxL1gI1V98RxRcqIT2sAob17i7amd-42I/edit#heading=h.i5ej7tig9g64

To Do

• Research usage cases for document stores
• Report that research out to the team for discussion

Review Checklist

• Presentation was helpful to the team and answered the needed questions.

Trello Source: https://trello.com/c/fq0UNi6X

Review Wireframes

Problem/Why

Brian needs someone to review his wireframes and provide feedback: https://trello.com/c/70OxP7ut/27-wireframe-user-password-reset-lost-password-views

---

Goal/What

Determine the review requirements and provide feedback.

---

Solution/How

Ask questions via Trello and Teams. Review wireframes with Adobe XD. Provide feedback in Trello and Teams, as necessary.

---

To Do

• Review the wireframes
• Review the wireframes for the second iteration

Trello Source: https://trello.com/c/WAuQyqqM

Laravel lighthouse presentation

Problem/Why

Laravel has been chosen as the backend with a GraphQL API interface. The dev team needs to understand how to implement a GraphQL API in a Laravel application.

---

Goal/What

Lighthouse is a Laravel extension for creating GraphQL interfaces. We'll create a presentation describing basics of how to use Lighthouse to create a GraphQL interface.

To Do

• Getters/Resolvers
• Mutations

Trello Source: https://trello.com/c/04P6Trx6

Set Up Sanctum

Problem/Why

There is currently no way for users to authenticate from the client to the backend on CCR. It would be costly to develop an authentication system from scratch.

---

Goal/What

Implement Sanctum as an authentication system to handle user logins.

---

Solution/How

Install Laravel Sanctum as a Composer dependency: https://laravel.com/docs/8.x/sanctum#installation

---

To Do - 2021-01-11

Backend

• Setup Sanctum Lighthouse middlewares (Lighthouse Docs)
• Create login mutation in lighthouse (Lighthouse Docs)
• Create a mock user (Laravel tinker)
• Test using /graphql-playground login mutation

Client

• Extend login form to use apolloclient/graphql login endpoint
• Answer question: How is logged in state stored?

To Do - 2021-01-05

• Install Laravel Sanctum as a composer dependency
• Test if Sanctum is installed correctly and works as expected
• Configure Sanctum as described in the Laravel documentation

Review Checklist

• Sanctum issues a cookie to mitigate CSRF
• Sanctum issues a session cookie when successfully authenticated

Attachments

• Is child to System User Authentication

Trello Source: https://trello.com/c/ICQyqnbW

Investigate Apollo and GraphQL

Problem/Why

Since decided to use GraphQL as our API layer our team needs to gain knowledge on the Apollo GraphQL query language and its integration with PHP Laravel.

---

Goal/What

Prepare a presentation or develop a sample app to demonstrate the usage of Apollo GraphQL

---

Solution/How

Reading blog posts, tutorials, developing a test app to familiarize ourselves with the technology and share knowledge

---

Review Checklist

Acceptance Criteria

• A presentation or an app demonstrating the usage of the technology is disseminated among the team.

Accessibility Checklist

Trello Source: https://trello.com/c/6pytJ5iL

Wireframe User management pages

Problem/Why

Need wireframes to describe the intended functionality for the admin user management pages.

---

Goal/What

Create wireframes for user management pages.

Review Checklist

To do

• Wireframe for user index page
• Wireframe for user edit page
• Wireframe for user create page

Attachments

• https://trello.com/c/WAuQyqqM/39-review-wireframes

Trello Source: https://trello.com/c/kFNxrHfP

Add test harnesses for front end

Info here:

Quasar: Testing and Auditing

Once integrated it needs to be added to the github workflows (including codecov)

User Roles and Permissions

Problem/Why

For security reasons, not all users can have the same level of access to all resources and functionality within the system. The current system does not identify the roles and permissions of users and has no enforcement of what actions within the system that users are allowed to perform.

---

Goal/What

Implement into CCR a framework of user roles and user permissions so that user behavior can be limited as specified out of concern for security.

1. User roles
2. User role management
3. User permissions
4. User permission management

---

Solution/How

https://trello.com/c/BAEsAQBu/61-develop-user-roles

https://trello.com/c/Np2eCHPM/62-develop-user-permissions

---

To Do

• https://trello.com/c/BAEsAQBu/61-develop-user-roles
• https://trello.com/c/Np2eCHPM/62-develop-user-permissions

Review Checklist

Attachments

• CCR Actions by Role
• Is parent to Develop User Permissions
• Is parent to Develop User Roles

Trello Source: https://trello.com/c/zqmBjbeb

Add database schema and GraphQL endpoints for user profile data

Problem/Why

There is currently not a way for users to describe metadata about themselves into the applicaiton.

---

Goal/What

The user database should include profile data about users. Reference the metadata collected in #64 for the types of information that should be collected.

---

Solution/How

The implementation in the database should be flexible so as to not require database migrations to add user metadata fields in the future, especially as these fields do not need to be queried / joined individually. If there are some fields that would be joined / filtered against, those should be added as columns directly.

---

To Do / Acceptance Criteria

• Create a new JSON column on the users table for storing user profile metadata
• Add the user profile metadata field to the user type in the graphql schema
• Add the user profile metadata field to the existing updateUser mutation
• Implement tests to ensure the data can be queried and mutated.
• Implement profile metadata validation (only accept known fields, and set reasonable max length limits)

Review Checklist

• Tests pass
• User profile data is stored and associated with the user.
• User profile fields are flexible.

Expand Upon Apollo App

Problem/Why

Currently, the Vue apps that Grant created Tuesday, October 27th are using a publicly-consumable GraphQL endpoint that doesn't support mutations or work with data structures that closely resemble those that will actually be used in CCR. There is also no interactivity within these apps between web page elements on the client and a GraphQL endpoint on the server.

---

Goal/What

Make the existing apps use a simple GraphQL endpoint that can be ran locally and customized for mutations. Demonstrate a simple user login form using this endpoint.

---

Solution/How

Add the graphpack-built GraphQL endpoint to the existing repository. Expand its schema as necessary for querying and mutating. Add a simple login form. Write frontend code to handle submitting a login request as a POST. Write code handle request and return a response to the frontend. Write frontend code to handle response and change interface as necessary.

---

To Do

• Add GraphQL package to repo
• Update schema of GraphQL endpoint
• Hook up Vue apps into GraphQL endpoint
• Add page routing functionality
• Add a page for a simple login form
• Add Vue component for a simple login form
• Write code for sending a POST request from the login form
• Write backend code to handle request and return a response
• Write frontend code to handle response from the backend

Trello Source: https://trello.com/c/hrQaFsaF

Document branching/merging plan & integrate tooling to enforce/encourage

Problem/Why

Branching/merging plan isn't currently documented

---

Goal/What

Clear expectations of how to branch/merge/commit/contribute to the codebase.

---

Solution/How

Update the contributing.MD file to reflect current and desired practices. Integrate tooling (semantic-pull-request, conventional-changelog) to enforce desired practices generate artificats from them (changelogs, releases, etc)

---

To Do

• Update contribution guidelines
• Integrate lint-pr

Review Checklist

• Contribution guidelines match team norms.
• PRs on protected branches are linted to ensure that conform to team norms.

Trello Source: https://trello.com/c/SgaLejdO

Create an account

A user should be able to make an account with an email address

Checklist

• User gets a conformation email
• User should be able to reset their password
• Appropriate error messages are displayed when the user is creating an account (in case of a failure)
• Confirmation emails expire after a certain amount of time
• Confirmation emails are not flagged as spam

Basic User Access - Authentication

Problem/Why

In the existing system, there is no definition of a user in the system. Users cannot currently sign in to the system or be recognized by the system as signed in. Users may want to authenticate using the login system provided by the app.

---

Goal/What

Create a system that allows users to authenticate. Its sign in functionality should:

1. Accept email and custom password pairs.

2. Accept logins from external providers (like Google).

3. Notify users if their account is locked.

4. Provide options to reset password when authentication fails.

---

Solution/How

Implement local authentication - Architect data structures for storing user credentials. Create a view with Quasar for a form for sign in. Write front-end code to validate input. Write front-end code to POST sign to the back-end. Add a route for handling POST requests for authentication. Write back-end code to validate the user input from authentication route against database stored credentials. Write front-end code to handle responses from authentication route.

Acceptance Criteria

Review Checklist

Accessibility Checklist

Attachments

• Is parent to Accept email and custom password pairs
• https://trello.com/c/kFNxrHfP/29-wireframe-user-management-pages
• https://trello.com/c/70OxP7ut/27-wireframe-user-password-reset-lost-password-views
• Is parent to Connect Apollo Client to Lighthouse
• Is parent to Implement Apollo Client state management library
• Is parent to Setup Sanctum on the existing backend application

Trello Source: https://trello.com/c/XK8oNtaj

Develop Quasar App for Local Authentication/Registration

Problem/Why

Currently, the apps that Grant has worked on in researching Apollo and authentication are as follows:

• Vue 2 app with Apollo for GraphQL integration and no authentication
• Vue 3 app with Apollo for GraphQL integration and no authentication
• Quasar/Vue2 app with authentication via Firebase

Firebase is likely not going to be part of the production stack for CCR.

---

Goal/What

Develop a Quasar app that does not use a remotely hosted third-party service (like Firebase) to authenticate users and store and retrieve their data.

---

Solution/How

Create a new app with Quasar, Laravel, Sanctum, Lighthouse, and Apollo Client. Hookup the Quasar frontend to use the authentication functionality on the backend.

---

To Do

• Create a new Quasar app
• Install Laravel Sanctum
• Add a login page with components for email and password inputs
• Add frontend code to submit authentication requests from the frontend
• Install Laravel Lighthouse
• Install Apollo Client

Attachments

• GitHub Repository

Trello Source: https://trello.com/c/249lrJni

Create an Apollo/Vue.js Demo Application

Problem/Why

In the interest of developing the initial authentication piece of CCR, our team is currently indecisive on proceeding with Apollo Client as the client library of choice for interfacing with a GraphQL endpoint.

---

Goal/What

Develop a demo application from a tutorial to explore and evaluate Apollo Client and its usage with Vue.js

---

Solution/How

Follow this tutorial series: https://apollo.vuejs.org/guide

Estimated Word Count: 9400

Organize a simple presentation for our sprint review meeting on October 28th to demonstrate the application and share takeaways/feedback.

---

To Do

• Vue 3 version
• Vue 2 version

Trello Source: https://trello.com/c/iCn97abp

Move away from JWTs for auth

After a good bit of reading JWTs just not the right way to go. The biggest problems lie in there being no way for the server to invalidate a token.This makes logout a bit of a farce in that while the client discards the token, if the token has been acquired by anyone else it is still valid until the token itself expires.

(There are a lot of blog posts just search Google for more information on this part.)

This also means that if the user changes their password any previously created tokens will still be valid until they expire.

Option 1: implement an OAuth2 Server

This is probably overkill for an application like this. CakePHP does not have an implementation currently however Laravel does (Laravel Passport). Almost all use The PHP League’s library as a basis for their implementation which we could certainly do as well. Configuring and implementing OAuth2 is non-trivial.

Option 2: Return to using PHP sessions

We’d only use sessions to make authentication stateful (we would still not store any application state information in the backend). Using DB storage for these sessions would allow us to invalidate sessions as needed.

Blog post with a similar conclusion

We would still create the opportunity for some users to create long-lived bearer tokens for integrations and other things outside of the client application.

Logging in through other services would likely be done through openid connect.

Facebook
Google

Basic User Access

Problem/Why

There are a number of necessary core features that are not yet completed and expected by all to be included in an initial release of the application.

---

Goal/What

Address and implement features to handle the following:

1. User authentication - sub-epic
   1. Internal - connected frontend and backend for authentication
   2. On-Hold External connections - authentication providers
      1. Google
      2. Twitter
      3. Facebook
   3. Create a system that allows users to authenticate. Its sign in functionality should:
      1. Accept email and custom password pairs.
      2. Accept logins from external providers (like Google).
      3. Notify users if their account is locked.
      4. Provide options to reset password when authentication fails.
2. User registration - sub-epic
   1. Improve user login and registration
   2. Add missing unit tests for creatUser mutation
3. User Profiles - sub-epic
   1. Identify what metadata is needed
   2. Expansion of user profiles - associate metadata with user
   3. Updating user information

---

Solution/How

Resolve the child issues related to this Epic.

Trello Source: https://trello.com/c/d6gi4IcT

Learn, investigate, and present on Vue.js

Problem/Why

Our team decided to use Vue.js for the CCR app. Educating myself with the technology and presenting the knowledge gained during the process maybe beneficial for the team.

---

Goal/What

Prepare a presentation or develop a sample app to demonstrate the usage of Vue.js

---

Solution/How

Read online tutorials, Vue.js documentation, etc to gain knowledge on Vue.js that would assist in building a demo application

---

Review Checklist

Accessibility Checklist

To Do

• Publish artifacts to Github

Trello Source: https://trello.com/c/b7nvDuYT

Identify a wireframing tool

Problem/Why

We need a common tool to use for creating and sharing wireframes. We currently do not have one.

---

Goal/What

Identifying a preferred tool to build wireframes collaboratively.

---

Solution/How

To present options with their pros and cons for team to decide and/or identify which ones the administration will pay for.

Team votes on preferred tool.

---

Acceptance Criteria

• We all need access to the same tool
• It needs to be able to be collaborative on projects
• Works on various operating systems/browsers
• Is meant to build wireframes

Trello Source: https://trello.com/c/ZKHmwtNF

Set up backlog board

Problem/Why

We need a place to track what we're working on without spending money.

---

Goal/What

We want a tool that enables us to track the tasks that we're working on, to be able to let everyone see what work is needed and how it is progressing and to be able to edit/contribute. It should be easy to use and organize. Would prefer it to be integrated with our other tools.

---

Solution/How

Try multiple platforms: planner, trello, etc.
Identify any issues with each.
Identify plugins that could improve the platform and make our workflow easier.
Discuss and agree to a template for creating "tickets" - what to capture and in what way

Success/acceptance requirements
We have a working prototype of a board for us to use during our first release. We can review and revise during retrospectives.

Acceptance Criteria

• Everyone has access
• It is easy for all team members to use
• Is adaptable to our needs
• Most desired features are present in tool

Review Checklist

Accessibility Checklist

Trello Source: https://trello.com/c/pz6WcIYD