Jumubase

Jumubase is a tool for organizers of Germany's largest youth music competition – Jugend musiziert, or "Jumu" in short. The software powers jumu-weltweit.org, a competition hub for German schools across Europe.

The application serves two main audiences:

• Jumu participants and their families, friends and teachers; they can sign up for a contest, edit their information, and check schedules and results without a user account.
• Jumu organizers on both local and global level, who can manage contest data, enter results and print contest-related material. The permissions for this are granted via personal user accounts.

Jumubase also exposes some public data, such as timetables and results, via a GraphQL API that serves a mobile app available on Android and iOS.

Setup instructions

Jumubase is built with Elixir and the Phoenix framework. Follow these steps to set up a local environment:

0. Clone this codebase
1. Install Elixir
2. Install PostgreSQL, e.g. through Postgres.app
3. Install Chrome or Chromium for PDF generation, e.g. using brew install chromium --no-quarantine
4. Install Elixir dependencies with mix deps.get
5. Install JS dependencies with cd assets && npm install
6. Create, migrate and seed the local database with mix ecto.setup
7. Start Phoenix endpoint with mix phx.server

Then, point your browser to localhost:4000.

Release instructions

Ensure the following environment variables are made available to the app:

• DATABASE_URL – Set automatically e.g. on Fly.io when provisioning a database.
• POOL_SIZE – Depends on how many database connections are allowed by the plan. Leave some room for occasional one-off mix tasks such as migrations.
• SECRET_KEY_BASE – Can be generated using mix phx.gen.secret.

Documentation

Domain vocabulary

Many schemas / data structs in this app are inextricably linked with the "Jugend musiziert" competition. The following list serves as a brief explanation to those unfamiliar with the domain:

User
A user of the software, identified by their email and password.

Host
An institution, typically a school, that can host contests. Each host belongs to a grouping, whose local contests lead to a single 2nd-round contest. Hosts can change grouping between seasons, in which case their historical contests stay with the original grouping.

Stage
A location where performances take place. Every host has at least one, but often several stages.

Contest
A single- or multi-day event during which performances take place. Besides its associated host, it includes a season (= competition year) and a round.

Category
A set of constraints for participating in a contest. Each category is designed either for solo or ensemble performances and mandates what pieces can be performed, as well as a min/max duration that depends on the performance's age group.

Contest category
A manifestation of a category when offered within a particular contest. This schema exists to hold additional constraints: Some contests might offer a category only for certain age groups, or not at all.

Performance
A musical entry taking place within a contest category, at a given time and venue. It is associated with an age group calculated from the birth dates of the soloist or ensemblists (but not accompanists).

Appearance
A single participant's contribution to a performance. It holds the participant's instrument and role (i.e. soloist, ensemblist or accompanist, the first two being mutually exclusive). It also stores its own age group, which for accompanists can differ from the performance's age group. Each appearance is awarded points by the jury, and a certificate is given to its participant afterwards.

Participant
A person appearing in one or more performances within a contest.

Piece
A piece of music presented during a performance. It holds information on the composer or original artist, as well as a musical epoch.

Parameters

Some Jumu-related data (such as rounds, roles, genres, and category types) is unlikely to change much over time and therefore hard-coded into the JumuParams module. Parameters that are likely to change, or not meant for the public eye, are stored as environment variables instead.

Authentication

phx.gen.auth is used for user authentication. Users can be associated with one or several hosts, typically for the reason of being employed there and acting as local organizers. They can only manipulate resources "belonging" to those hosts.

Each user has a role assigned to them:

• Local organizers may access only contests of their associated hosts
• Global organizers may access contests in their associated hosts' current groupings
• Inspectors get read-only access to data for statistical purposes
• Admin users have full privileges

License

Jumubase is published under the MIT License.