Welcome to the quickstart guide! We’ll take you through the steps to begin coding features for Dolphin Flashcards
The project uses feature branches, which are made from the development branch
The frontend, stored in the frontend
folder is a React app. Therefore, you need to install everything you normally would for a React project, including npm
. The frontend will always communicate with the deployed api server http://dolphinflashcards.com/api
. You can change this URL in frontend/src/api/config.js
if needed, but remember to revert it before making a pull request (the file should be in the gitignore).
Here’s what you need to do before beginning development on Dolphin:
https://github.com/jacob-macleod/Dolphin-Flashcard-App
git clone [...]
)cd Dolphin-Flashcard-App
cd frontend
Enter the following commands:
npm install
which will install everything in frontend/package.json
npm serve
The React app will be accessible at http://localhost:3000
.
The React app is built into static files when running in production. More information on this is below, in the Serving the frontend
section.
The backend consists of an API, which is being documented in docs/
. The API is made up of functions to handle storing and reading data in different ways. For example, the route to update the streak reads the current streak being looked at, calculates the new streak, and saves it to the database.
In production, Google Firebase is used as a database, and in development, either the production Firebase instance, a dev instance, or local json files can be used. To determine whether Firebase or local json files are used, backend/database/database_config.py
is looked at.
type="production"
, the production Firebase server is used.type="local"
, a local firebase server is used.Depending on the value of the type
variable, either the FirebaseDatabase
or LocalDatabase
classes are initialized, and the initialized instance is stored by the Database
class as db
. FirebaseDatabase
and LocalDatabase
inherit from the DatabaseAbstract
abstract class, and so must have get
, save
, and increment
methods. For either class, these are used in the same way.
Note that API documentation is in docs/
.
To contribute to the backend, using a local Firebase setup, follow these steps:
cd
into it.pip install -r requirements.txt
.backend/database/database_config.py
stores type="local"
.bash firebase_emulator.sh
- this runs a local firebase docker image for development.
firebase_emulator.sh
is currently only available for Linux, but since it only uses docker and a curl
command, it should be fairly easy to port to Windows.docker
and curl
are required to run the emulator.python3 backend/main.py
.Then, you can go to different API routes - go to <the url flask prints when you run the code>/api/<the API route>
.
Follow these steps:
Clone the repository and cd
into it.
Run pip install -r requirements.txt
.
Make sure backend/database/database_config.py
stores type="production"
.
Create a new firebase project. You can use this guide to help.
Create the following files in the root repository of the project:
firebase_url
- stores the URL of the firebase instance.firebase_config.json
- stores the Firebase config - a json file containing apiKey, authDomain, etc.credentials.json
- the service account credentials for interacting with the database.These files are added automatically when the code is built for the server.
Run python3 backend/main.py
.
Whichever method you use, you can develop the frontend independently of the backend by referring to the relevant section. Or, you can run them together, like in production. To do this, enter the following commands:
cd frontend
.npm install
which will install everything in frontend/package.json
.npm run build
.This will build the React app to frontend/build
. Then, the server will serve the static files in that folder. Therefore, the backend server must be running first.
The documentation for Dolphin Flashcards is stored in .mdx
files. While you can read them in their raw versions, it is much easier to use the deployed documentation website at https://docs.dolphinflashcards.com.
When making changes to the documentation locally, you can run these commands to run a local website storing the documentation:
npm i -g mintlify
cd docs
mintlify dev --port 3333
A new window will open in your browser showing the documentation
When contributing, follow these general guidelines:
PATCH:
, MAJOR:
, or MINOR:
.backend/__init__.py
:
CHANGELOG.md
, following the standard there.testing/
.