Code Walkthrough

Overview

The code for G2A is quite complex, and consists of several (somewhat disjointed) parts. Roughly speaking, there are three main parts:

• Python Code: Responsible for much of backend processing, database storage, etc.
• React: Responsible for frontend components. We use the dated class-component structure of React so any documentation you read on this framework should follow that. An important note is that hooks cannot be used in these components due to this.
• Vanilla JavaScript: Creates interactions between React and Python, namely in the api.js file

This page will act as a high level overview of where things can be found. For information on how these things interact, see code flows to get a better idea of the specifics.

Python

views.py

views.py is most interacted with and contains many functions that access the database and modify data elements on the site. It is located in "PPUC/PxPUC/views.py".

Methods/Classes

• ResearcherSearchList is one of the most important and largest classes. This class is used by React files and api.js to display the list of search results in the contract search tool.
• get_queryset() is essentially the main method and encapsulates all other methods in the class. It returns a QuerySet object, using the filter constructed from build_filter() method
• build_filter() is used to strip and parse the search query as it was typed in the search bar

models.py

• models.py defines the database object classes for the site.
• Location is primarily a reference object used to tie together other relevant objects (Contracts, Sentences)
• Question is used for entries on the FAQ page

serializers.py

• This defines the structure for how data objects within models.py are formatted such that they are usable by the frontend components (using Javascript)

urls.py

• This deals with defining where resources are located (resources meaning the various views that deal with querysets) and can be seen as the final part from the python backend to the javascript frontend before it reaches api.js

setup_app.py

• The setup script calls all of the other important scripts and is responsible for updating any data changes to the master sheet. It will be called when the repo is first cloned through the setup process, but should be used any time a data change occurs

add_contracts.py

• This script handles the location, contract, and sentence model population process. It is called by the setup_app and takes the longest to execute (can even take an hour)

read_master_sheet.py

• This script (only within the read-in-spreadsheet branch until that is brought to main) deal with parsing the master excel spreadsheet. It populates the newer models defined by SP23 and SU23.

Javascript

api.js

• API calls are directed here and this is the connection point between the frontend and backend as it interacts directly with the components and urls.py
• It deals with promises (the .then() section) and sending these to the frontend to be used like in the search process.

App.jsx

• This component handles all of the other components and sets the skeleton for the website including the navigation bar
• If there is a state variable that you want to share across components, you will need to lift the state up to App.jsx and send the variable down as a prop to be used by other components (see React docs).
• This occurs because React components form a tree structure, where each component has a parent component that is rendered before it. Data cannot be shared between siblings without first going through a parent. This idea can be seen within the state variables defined in Researchers.jsx to ResearcherResult.jsx and ResearcherResultSentence (within ResearcherResult.jsx).

Commentary.jsx

• One of the more important components, this one handles the search box and the initial search bar. It redirects to Researchers.jsx

Researchers.jsx

• This component is the parent of ResearcherResult.jsx and deals with the second page of the search process.
• Once a user searches something, they are brought here for results to be displayed.

ResearcherResult.jsx

• The actual displaying of individual results is done within this component which is called from inside of Researchers.jsx.

Location.jsx

• The final step in searching, once a result is clicked on this component is rendered.
• Contracts are displayed here

---