Data flow documentation

[adelevie]

Admin data flow

An admin is authenticated via GitHub-provided OAuth (using the omniauth-github gem) and authorized via a whitelist of GitHub user IDs (see GitHub documentation for instructions on obtaining a canonical ID for a GitHub user.) The whitelist is public, version-controlled, and located at config/admins.yml. Only persons who are permitted to have read and write access to all data are included on the whitelist.

Successful authentication results in the creation of a session which stores a unique identifier of the user.
Logging out occurs after a successful GET request to /logout. Logging out results in the destruction of the previously-mentioned session.

---

#### End-User Registration Data Flow

The registration data flow describes the process by which both admin and non-admin users register to use the Micropurchase website.

In screen 1, the user is logged out, and clicks on a button taking them to /login. /login is a public-facing page that includes information about registration as well as any terms that must be agreed to before proceeding.

On screen 2, when the user clicks "Authorize with GitHub", they proceed through the GitHub OAuth flow. After granting the Micropurchase OAuth application permission to access public information from their GitHub account (on screen 3), the user is redirected back to the Micropurchase website (screen 4).

If the GitHub ID does not exist at this time in the Micropurchase database, a new user record is created. Screen 4 contains a form where for non-admin users to enter their DUNS number. Upon submission of that form, the DUNS number is saved as part of that user record. A DUNS number is public information. At this stage, there may be validation of the DUNS number. Such validation may include a request to the SAM.gov API to ensure authenticity of the DUNS number and/or to retrieve public information associated with that DUNS number from SAM.gov. This public information may be presented back to the user for confirmation, and this information may be stored in the Micropurchase database as part of the user record.

Once a user has submitted their DUNS number, they may place bids, using the bid data flow described above.

Successful authentication results in the creation of a session which stores a unique identifier of the user.
Logging out occurs after a successful GET request to /logout. Logging out results in the destruction of the previously-mentioned session.

---

#### Bid data flow

The bid data flow describes the creation of bid records in the database. This diagram assumes a user is already registered and logged in (e.g. authenticated). In screen 1, the user clicks on a an individual auction listing and is taken to screen 2. In screen 2, the user types a bid amount into a form, and clicks submit. The same either page re-renders or the user is redirected to another page. Meanwhile, if the bid amount passes validation checks on the server, a new bid is saved in the database.

The bid list screen displays a list of bids for a given auction. All bid data is considered public and not procurement sensitive. At the discretion of the Micropurchase team, some data (such as identity of the bidder) may be redacted while an auction is currently running. However, all users will be given notice and must consent to the publishing of all bid data (and potentially other usage data) before registering and before bidding. Terms will be consistent and made clear to users. Those terms may change from auction to auction, however, terms will be consistent within each auction. All bidding data will be released when an auction ends.

---

[adelevie]

@NoahKunin I updated the data redaction section to reflect our understanding after chatting in #micropurchase.

[allalala]

@adelevie is this 👍 to close?