This repository contains both the backend API files and frontend React site files for the EndLessLEarner team at the University Of Central Florida's Center for Humanities and Digital Research.
The backend uses the Flask web framework and the Flask RESTful extension to make REST APIs in Python. The frontend is built using React and Bootstrap and bundled with Webpack and Next.JS. The main database used is MySQL, with some endpoints using a Redis database to improve performance and other endpoints using a mailing server for sending emails.
When "CHDR server" or "Production" is mentioned, we're talking about the CHDR server (located at https://chdr.cs.ucf.edu) that the ELLE application is hosted on.
To get started, check the quick start guide!
Production server: The ELLE website is hosted at https://chdr.cs.ucf.edu/elle and the API is hosted at https://chdr.cs.ucf.edu/elleapi.
Development server: Future SD teams, create your own website and API development server by following the dev server guide.
If you would like to improve upon the website, please check out the todo list!
Python Version: >= 3.10.12 Node Version: >= v20.11.0
resources/: API functions are defined under related files in this folder e.g. APIs related to terms are in theterms.pyfile under resources folder. Those functions are used in the__init__.pyfile to set up routing..env: All Python secrets are stored here in the root folder. Step 14 of the dev server guide explains what goes into it.__init__.py: Main file that starts the API. All the APIs are imported there as resources and are used to set up API endpoints.config.py: Contains configuration variables used by the API.utils.py: Contains helper functions that are used by the API functions.db_utils.py: Contains functions that interact with the database.exceptions_util.py: Contains functions that deal with exceptions within the API resources.
API documentation on Postman: https://documenter.getpostman.com/view/25426921/2s93JnT6RM (To be updated)
- The backend needs to be connected to an SMTP server (just an outgoing SMTP server is file) so that it can send out emails to the users (to reset password, to get the username, ...)
- The email APIs were tested with Postfix MTA
- The backend uses a Redis database as an in-memory cache system to cache some information
- Once Redis is installed, install the Python Redis package (included in the requirements.txt file) and update the Redis config information in
config.pyso that the API can interact with the Redis database
- Once Redis is installed, install the Python Redis package (included in the requirements.txt file) and update the Redis config information in
- The current backend implementation assumes that the website files are located under the
templates/build/folder and redirects any calls to/endpoint to theindex.htmlpage located under thebuildfolder
- It's not recommended to run the Flask app in debug mode using the built-in server in a production server. Consider using a different server such as WSGI to deploy the Flask app in a production server. (As of Spring 2023, this reccommendation is currently not being followed.)
Terms, words and their translations along with other information:
- Types:
- NN (Noun)
- VR (Verb)
- AJ (Adjective)+
- AV (Adverb)
- PH (Phrase)
- Genders:
- MA (Male)
- FE (Female)
- NA (Nongendered)
- Front/Back clarification
- Front is the word in the foreign language (prompt),
- Back is the word in the native language (answer)
- Types:
- MATCH (Base type, uses a term as the question prompt, only one answer)
- PHRASE (Identical to MATCH, but for whole phrases, only one answer)
- IMAGE (Select a word corresponding to an image, may have multiple answers)
- AUDIO (Select a word corresponding to audio, may have multiple answers)
- LONGFORM (Questions with a full text prompt, may have multiple answers)
Since the front end was created using nextjs, the file organization here is how a typical app created using it looks like.
templates/
├── .next/ # Contains the build files that are created when the build command is read and are read by production/development servers
├── app/ # Contains layouts for the pages and various global settings for TypeScript to use. Currently only has one and might not be the best implementation
├── components/ # Contains all of the React components used within the website. Some directories might be a bit messier than others.
├── hooks/ # Contains a couple of custom hooks for authentication and Pasta Kerfuff-ELLE related data (Should be added to! See `usePasta()` for an implementation)
├── lib/ # Library files for some of the (likely outdated) libraries we use. Bootstrap was recently updated to v5 as of Spring 2024.
├── node_modules/
├── pages/ # Contains the page files for the Next.JS server to identify and host on an identically-named path. ('home.tsx' -> 'http://localhost:3000/elle/home')
├── public/
│ ├── games/ # Unity game WebGL files go here in the respective folder!
│ │ ├── AnimELLE-Crossing/
│ │ ├── Card-Game/
│ │ ├── Maze-Game/
│ │ ├── Pasta-Game/
│ │ └── README.md
│ └── static/ # Contains static files (images, css, json, etc.) for the application. While games are technically static, they are not included here.
├── services/ # Contains services that replace the need for long axios calls in components. Used primarily by the custom hooks above (Should be added to!)
├── types/ # Contains type definitions for the api and database. Any type definitions should be included here.
├── middleware.ts # This file intercepts page navigations and or api calls to run code prior to their execution. Mostly used for redirects.
└── next.config.js # The main configuration file for Next.JS. Contains Webpack configuration rules and redirect/rewrite rules.
- Unity WebGL Games
- This website hosts VirtuELLE Mentor, The ELLE MAZEing Race, AnimELLE Crossing, and Pasta Kerfuff-ELLE using their Unity WebGL builds. For versioning sake, the games are not included in this repository.
- Before hosting the game files on the website, see this README
- If you want to put a Unity WebGL game on the website, it must be built using Unity 2020.3 or higher! This is because the version of the react-unity-webgl package we are using only supports that Unity version
- It is suggested to be using the latest Unity LTS version.
- When building the game for WebGL in Unity, click on
Player Settings...in the build menu, then make sure thatCompression Formatis disabled.- This is because the CHDR server is currently not setup to allow browsers to perform decompression natively while it downloads the build files.
- Info on finding and using this setting
See the dev server setup guide.
__init__.py
# Change URL prefix of the API e.g. https://chdr.cs.ucf.edu/elleapi
API_ENDPOINT_PREFIX = '/elleapi/'
# Change port the API runs on
app.run(host='0.0.0.0', port='5050', debug=True)- SQL keywords in capital letters
- Backticks around identifiers
- Use
%sin your query strings whenever possible as opposed to using f-strings. That avoids any chances of SQL injections
- Use camelCase
- Use underscore
- Use docstring as an overall summary of the API call
- Otherwise use #
The UCF Center for Humanities and Digital Research server is currently hosting the ELLE website and API.
__init__.py
# The website redirects the API to be located at /elleapi/, so we need to change the endpoint prefix.
- API_ENDPOINT_PREFIX = '/elleapi/'
+ API_ENDPOINT_PREFIX = '/'/templates/package.json
"scripts": {
"dev": "next dev",
"build": "next build",
// A service is already using the port 3000 in production, so we need to use 3001.
- "start": "next start",
+ "start": "PORT=3001 next start",
"lint": "next lint"
},
To view the previous README documentation we inherited, go here.