README.md (4251B)
1 # My Heats 2 Live heats, scoring and leaderboard for sport events. 3 4 This React application was build using [Vite](https://vitejs.dev) (`npm create 5 vite@latest . --template react`) and the following core componentes: 6 * [`react-router-dom`](https://reactrouter.com) for routing between the React 7 components 8 * [`postgres`](https://github.com/porsager/postgres#realtime-subscribe) for 9 realtime subscription to leaderboard changes with PostgreSQL publication 10 * [`react-select`](https://react-select.com) for the selectbox widgets 11 12 ## Running the App 13 ```bash 14 # Install dependencies 15 npm install 16 17 # Export all required environment variables, see example in .env 18 19 # Start authentication API backend 20 npm run api 21 22 # Start app frontend 23 npm run dev 24 ``` 25 26 See `./docs` for more detailed developer documentation. 27 28 ## Scoring and ranking logic 29 The scoring and ranking logic is defined in `utils.js` inside the `rankByHeat` 30 function. Following ranking options can be selected. Rank by: 31 * Start number: Rank by athlete start number 32 * Best heat: Rank by best heat (and by least worst if "best" is equally good) 33 * Worst heat: Ranks worst heats only (no further comparison by best if equally 34 bad) 35 * Total: Ranks by sum of all selected heats 36 37 ## Database schema 38 The PostgreSQL database schema is stored in the `schema` folder and can be 39 created using plain psql. 40 41 To update the schema from the current database, use (example for table 42 `startlist`): 43 ```bash 44 pg_dump -h 127.0.0.1 -U postgres -t 'public.startlist' --schema-only > schema/04-startlist.sql 45 ``` 46 47 The views and functions from `./schema/99-init-db.sql` are required. Among 48 others, this enables [PostgreSQL 49 publication](https://www.postgresql.org/docs/current/logical-replication-publication.html) 50 so the leaderboard can automatically update scores when they are created or 51 changed by judges ("realtime functionality"). 52 53 ## Authentication with magic links 54 Authentication of judges is performed using Magic links. 55 56 Sign up process for new judges: 57 * The judge is required to have a valid email address 58 * Judges can be invied to the scoring backend by invite only (table `public.judges`) 59 60 Sign in process: 61 * For sign in, the judge enters her email adress and receives a login link 62 * The login information is stored in the browser session until sign out 63 64 ## Real-time replication 65 The database user needs permissions to start `walsender`. Otherwise you 66 encounter this error: 67 ``` 68 must be superuser or replication role to start walsender 69 ``` 70 71 To give the permissions: 72 ```sql 73 ALTER USER myheats REPLICATION; 74 \du 75 ``` 76 77 Also, the wal level needs to be set to `logical` in the postgresql config. 78 Otherwise, this is the error message you will receive: 79 ``` 80 logical decoding requires wal_level >= logical 81 ``` 82 83 To set it in `postgresql.conf`: 84 ``` 85 # postgresql.conf 86 wal_level = logical # minimal, replica, or logical 87 ``` 88 89 Restart database. 90 91 ## Bulk import/export 92 Use direct postgres database access: 93 ```bash 94 psql -h 127.0.0.1 -U postgres 95 ``` 96 97 To import data from local csv: 98 ```sql 99 \copy public.scores from 'scores_rows.csv' DELIMITER ',' CSV HEADER; 100 ``` 101 102 To export data to local csv: 103 ```sql 104 \copy public.scores to 'scores_rows.csv' DELIMITER ',' CSV HEADER; 105 ``` 106 107 ## Settings 108 The following settings can be applied in `/settings` as parameters to configure 109 the them and appearance of the leaderboard: 110 * `style`: The color of the navigation elements, one of `yellow`, `blue` or `red` 111 * `logoUrl`: Add url to a logo to replace the default logo in the footer 112 * `showLogo`: Set to "false" to hide the logo in the footer 113 * `showVersion`: Set to "false" to hide the version in the footer 114 115 ## Development & contributions 116 For a list of contributors see the [AUTHORS.md](./AUTHORS.md). 117 118 * All source code is available in this repository. Contributions are always 119 welcome! Pull requests at https://pr.in0rdr.ch/repos/myheats 120 * A [Kanban 121 board](https://board.in0rdr.ch/public/board/c445667f1c999857f6149cad967fa44f196f2e9fef02069c5f5136e036dd) 122 documents plans, todos and decisions for further development of the project. 123 124 ## Community and support 125 For question and support visit 126 [#p0c/libera](https://web.libera.chat/gamja/#p0c) on IRC. 127 128 ## License 129 This work uses the MIT License. See [LICENSE](./LICENSE) for details.