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

​
1. Contributing to the Frontend Web App

​
1.1. Quick Explanation

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).

​
1.2. Initial setting up

Here’s what you need to do before beginning development on Dolphin:

  • Fork the main repository at https://github.com/jacob-macleod/Dolphin-Flashcard-App
  • Clone the fork (with git clone [...])
  • cd Dolphin-Flashcard-App
  • cd frontend

​
1.3. Running the React Frontend App

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.

​
2. Contributing to the Backend API

​
2.1. Quick Explanation

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.

  • If type="production", the production Firebase server is used.
  • If 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:

  • Clone the repository and cd into it.
  • Run pip install -r requirements.txt.
  • Make sure backend/database/database_config.py stores type="local".
  • Run 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.
  • Run 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>.

​
2.3. Using Firebase as the database

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.

​
2.4. Serving the frontend

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.

​
3. Developing Documentation

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

​
4. Some Extra Information…

When contributing, follow these general guidelines:

  • Do your work in a branch from the development branch, then create a pull request when you’re ready.
    • In your pull requests, prefix the title with PATCH:, MAJOR:, or MINOR:.
    • Update the version in backend/__init__.py:
      • If you’re making a patch, increment the right-hand side number by one.
      • If you’re making a minor change, increment the middle number by one.
      • If you’re making a major change, increment the left-hand side number by one.
    • This follows the semantic versioning standard.
    • Write about the changes you’ve made in CHANGELOG.md, following the standard there.
  • Add comments in issues to show what you’re working on.
  • Try to follow the coding style and conventions established in the project.
  • Try to write unit tests if you can - this may depend on what, in particular, you’re coding. The backend tests are in testing/.
  • Have fun!
  • Finally, if you have any questions or problems running the code, please ask me in an issue or create a new one!