Map Your Hero(ine)

This repository contains a survey application developed for the the Map Your Hero(ine) project, led by Roselinde Supheert. More information can be found at the project website

The survey asks participants about fictional characters they admire. Participants fill in basic factual information about the character and the work they appeared in, and then answer questions about their personal impression of the character. Once an entry for a character has been created, multiple participants can answer the personal impression questions for that character.

The survey is intended to pay particular attention to how representations of characters change (or do not change) in adaptations. As such, the survey allows linking works as adaptations.

The documentation below is intended for developers. For more information about the project's goals and findings, visit the project website linked above.

Before you start

You need to install the following software:

• PostgreSQL >= 12, client, server and C libraries
• Python >= 3.12
• Python virtualenv
• WSGI-compatible webserver (deployment only)
• Visual C++ for Python (Windows only)
• Node.js >= 22
• Yarn

How it works

This project integrates three isolated subprojects, each inside its own subdirectory with its own code, package dependencies and tests:

• backend: the server side web application based on Django and DRF
• frontend: the client side web application based on Angular

Each subproject is configurable from the outside. Integration is achieved using "magic configuration" which is contained inside the root directory together with this README. In this way, the subprojects can stay truly isolated from each other.

If you are reading this README, you'll likely be working with the integrated project as a whole rather than with one of the subprojects in isolation. In this case, this README should be your primary source of information on how to develop or deploy the project. However, we recommend that you also read the "How it works" section in the README of each subproject.

Development

Quickstart

First time after cloning this project:

$ python bootstrap.py

Running the application in development mode (hit ctrl-C to stop):

$ yarn start

This will run the backend and frontend applications, as well as their unittests, and watch all source files for changes. You can visit the frontend on http://localhost:8000/, the browsable backend API on http://localhost:8000/api/ and the backend admin on http://localhost:8000/admin/. On every change, unittests rerun, frontend code rebuilds and open browser tabs refresh automatically (livereload).

Recommended order of development

For each new feature, we suggested that you work through the steps listed below. This could be called a back-to-front or "bottom up" order. Of course, you may have reasons to choose otherwise. For example, if very precise specifications are provided, you could move step 8 to the front for a more test-driven approach.

Steps 1–5 also include updating the unittests. Only functions should be tested, especially critical and nontrivial ones.

1. Backend model changes including migrations.
2. Backend serializer changes and backend admin changes.
3. Backend API endpoint changes.
4. Frontend model changes.
5. Other frontend unit changes (templates, views, routers, FSMs).
6. Frontend integration (globals, event bindings).
7. Update technical documentation.

For release branches, we suggest the following checklist.

1. Bump the version number in the package.json next to this README.
2. Try using the application in production mode, look for problems that may have escaped the tests.
3. Add regression tests that detect problems from step 3.
4. Work on the code until new regression tests from step 4 pass.
5. Optionally, repeat steps 2–5 with the application running in a real deployment setup (see Deployment).

Commands for common tasks

The package.json next to this README defines several shortcut commands to help streamline development. In total, there are over 30 commands. Most may be regarded as implementation details of other commands, although each command could be used directly. Below, we discuss the commands that are most likely to be useful to you. For full details, consult the package.json.

Install the pinned versions of all package dependencies in all subprojects:

$ yarn

Run backend and frontend in production mode:

$ yarn start-p

Run an arbitrary command from within the root of a subproject:

$ yarn back  [ARBITRARY BACKEND COMMAND HERE]
$ yarn front [ARBITRARY FRONTEND COMMAND HERE]

For example,

$ yarn back less README.md

is equivalent to

$ cd backend
$ less README.md
$ cd ..

Run python manage.py within the backend directory:

$ yarn django [SUBCOMMAND] [OPTIONS]

yarn django is a shorthand for yarn back python manage.py. This command is useful for managing database migrations, among other things.

Manage the frontend package dependencies:

$ yarn fyarn (add|remove|upgrade|...) (PACKAGE ...) [OPTIONS]

Notes on Python package dependencies

The backend is Python-based and package versions are pinned using pip-tools.

Development mode vs production mode

The purpose of development mode is to facilitate live development, as the name implies. The purpose of production mode is to simulate deployment conditions as closely as possible, in order to check whether everything still works under such conditions. A complete overview of the differences is given below.

dimension	Development mode	Production mode
command	yarn start	yarn start-p
base address	http://localhost:8000	http://localhost:4200
backend server (Django)	in charge of everything	serves backend only

frontend server (angular-cli) | serves | watch and build

static files | served directly by Django's staticfiles app | collected by Django, served by gulp-connect backend DEBUG setting | True | False backend ALLOWED_HOSTS | - | restricted to localhost

frontend sourcemaps | yes | no frontend optimization | no | yes

Deployment

Both the backend and frontend applications have a section dedicated to deployment in their own READMEs. You should read these sections entirely before proceeding. All instructions in these sections still apply, though it is good to know that you can use the following shorthand commands from the integrated project root:

# collect static files of both backend and frontend, with overridden settings
$ yarn django collectstatic --settings SETTINGS --pythonpath path/to/SETTINGS.py

You should build the frontend before collecting all static files.