Code Flows

There are several "flows" through the code that are particularly common and will likely be relevant in future code changes.

The most common flow is: SomeReact.jsx -> api.js -> urls.py -> some_function() in views.py

Search Process Flow

• All components that handle the frontend can be found at PPUC/frontend/src/components/[any_filename].jsx with the most important components for searching being Commentary.jsx and Researchers.jsx
• Both classes have a method called handleSearch() which does exactly what it says, it takes a user search query and sends it to the backend to be dealt with. This is the parameter for the API call in these files.
• To interact with backend data, API calls are made in both files. It looks something like this: Api.getResearcherSearchResults(searchQuery).then((resp) => with the arrow pointing towards some function to deal with the resp (the JSON response received from the backend).
• This call is made on the frontend within a component and connects first to PPUC/frontend/src/libs/api.js which handles the API endpoints and the URLs they are found at. An example of this: ${Api.BASE_PATH}/locations where base path is simply PPUC or the root directory. In this instance, locations is a pointer to a URL.
• These URLs are connected to the backend with PPUC/PxPUC/urls.py which defines where resources are able to found at. It also connects to PPUC/PxPUC/views.py that handles the logic of defining what these resources will be.
• In our case, a lot of these views return a queryset, or a list of sorts, pulling data from the SQLite database using Django operations. These querysets will follow the fields described within PPUC/PxPUC/serializers.py, using the corresponding serializer that is defined per view.
• For the search algorithm itself, this can be found in the method ResearchersSearchList within views.py. The bulk of the work is done within the for loop, as it iteratively shrinks the user query until it becomes just a single word. It filters in sentence and location objects relevant to the user query, both of which are objects/models defined in PPUC/PxPUC/models.py, and annotates new fields for rank which is just an ASCII letter grade.

Object Population Flow

• As mentioned above, the important data can be found to be defined within PPUC/PxPUC/models.py. Things like the sentence model, location model, and all of the new models added in SP23 and SU23 can be found here.
• Models deals purely with defining what a model will be, the fields/variables it will take on, and the relationships it will have to other models.
• Many of the older models (pre-SP23 and SU23) are connected to the location model (which in this case can be thought of as a contract that has contract text).
• How these models get populated with actual data to fill those fields/variables tends to vary. The older models tend to read from contract text files, either pulling the names out of the file titles in the case of location models, or pulling sentences out in the case of sentence models. The newer models (aka Provision, Keyword, Municipality, MasterContract, Department) all read from the master sheet found at PPUC/PxPUC/static/app/mastersheets (at the time of writing this, the sheet is only within the read-in-spreadsheet branch).
• In the case of the older models (with a focus on contracts, sentences, and locations), this data read-in occurs within the setup scripts. In particular, PPUC/scripts/add_contracts.py. Add_contracts handles all of the populating for these important models and follows the conventions defined in models.py as mentioned above.
• For the newer models, this data read in happens from the mastersheet as referenced above. This occurs in the setup script as well but within PPUC/scripts/read_master_sheet.py. To actually receive the contract text files from the master sheet, PPUC/scripts/download_contracts.py handles that. To reiterate, the last two mentioned scripts are only within the read-in-spreadsheet branch until that gets updated to the main branch.

Contract Display Flow

• As mentioned above, the contracts themselves are assigned to locations based on their filenames. These contracts are manually put into the repository and can be found here: PPUC/PxPUC/static/app/contracts_txt
• In the read-in-spreadsheet branch, there will be additional txt files that do not begin with the word "Pennsylvania". These txt files are the ones downloaded from the SP23 setup script and do not get used in displaying the contracts.
• Similarly, PPUC/PxPUC/static/app/contracts_pdf has the PDFs of the contracts which get displayed as well.
• After these contracts have been scanned and models have been populated as detailed above, a similar flow from backend to frontend exists that ultimately goes from views.py to a .jsx file, which happens to be Location.jsx in this case.
• This component gets a location from a result that a user clicked on (this is the final step of the searching process as a user clicks on a borough name from the search results page) and a contract variable.
• Within a set of Tabs of a Tab Pane, a contract is simply dumped out line by line. This does not involve the sentence objects despite the fact that the contract is dumped out in a line by line way.
• As far as scrolling and highlighting of the keywords go (a new feature also within the read-in-spreadsheet branch), a props variable called searchQuery is used. This searchQuery variable is the same searchQuery referenced above. It is shared amongst many components due to it existing in the parent component App.jsx. It is just the user's query they typed into the search bar. The scrolling is done within componentDidMount (a function called after React's render has finished execution) and the highlighting is done in the same location that the text dump is done.

FAQ Section

• Citizens.jsx contains the front-end code and api.js references to get the appropriate database objects.

Note: Much of the Citizens.jsx code should be deprecated, as it refers to database columns (i.e. Location ID) that have no use for this specific application.

• api.js is called for both Api.getLocationQuestions(0) and Api.getLocationStages(0). These refer to urls.py's "/location/0/questions" and "location/0/stages" respectively
• urls.py refers to LocationQuestionList and LocationStageList for Locations and Stages respectively
• views.py contains LocationQuestionList, which gets a queryset of questions from the database (queries Question.objects.all()). LocationStageList returns a JSON response containing the hard-coded "stages of a police complaint", which serve as rough categories for the questions.