Contributors Forks Stargazers Issues AGPLv3 license

Logo

ollaborative slot scheduling – APECS official website

This project is a web app for collaborative slot scheduling. See below for more details.

Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

  1. About The Project

  2. Getting Started

  3. Usage
  4. Roadmap
  5. Contributing
  6. License
  7. Contact
  8. Acknowledgments

About The Project

Screen Shot

This project is a web app for collaborative slot scheduling:

Given a set of volunteers to accomplish a predetermined set of task, the web app enables smooth handling of all voluntary participants.

Especially making sure that all slots are staffed and each volunteer does an equal amount of work. This project is currently deployed for french students in 2nd and 3rd years of medical school with the initative called “APECS”.

It is currently on its second year of daily usage with more than 300 registered users.

(back to top)

Built With

  • Vue
  • Python
    • Flask
    • gunicorn / uwsgsi
  • nginx
  • 3rd parties:
    • PostgreSQL (database)
    • Sendgrid (mailing service)

(back to top)

Getting Started

This project is built with Vue 3 for front end and python for back-end (flask is only used to handle remote procedure calls to fetch trainings data).

To work on the project you can either :

  • Run both locally
  • Run only the backend and query it with curl requests
  • Run only the frontend and feed the data using the production instance (beware of CORS issues)

For production, this projection also uses nginx as a front before accessing either front or back.

The training data is serialized in Json, images are included in byte arrays. The utilities to extract data into the proper format are not included in this repository.

Prerequisites & installation

The front-end is built with Vue and requires node to fetch the requirements:

npm install npm@latest -g

The back-end is built with Python and requires the usual pip query:

pip install -r requirements.txt

Third services required:

  • Sendgrid

This project uses the Sendgrid service to send mails to verify email adressed provided at signup and for forgotten password process. You have to get an API key and link it with the application via the SENDGRID_API_KEY env variable. You must also create corresponding mail template (currently hardcoded in the application).

  • Data base

This project is set up to use a Postgre SQL database. You have to setup a database and then provide the DB connection URL to link it with the application via the DATABASE_URL env variable. The URL looks like:

postgres://__login__:___password___@___server___:__port__/__path__

Database initialisation

A PostgreSQL must have been provided (see above), it can be initialised provided the following env variables:

DATABASE_URL=postgres://__login__:___password___@___server___:__port__/__path__ # URL to the PgSQL database
UNIQUE_CLASS_BATCH_ID= # a unique ID identifying the class batch corresponding to the imported data
                       # multiple class batches can be handled
DATA_TO_IMPORT_PATH=___path____.json # a json file following the format presented below

The data must follow the structure below:

{
	"planning": [{
		"h_date": "mercredi 7 septembre 2022", // date in french
		"amphi": "400", // optional
		"intitule": "RENTREE - PRESENTATION", // course title
		"ens": "Dr GUATTY", // attending teacher(s)
		"h_debut": "8h30", // starting time, in HHhmm format, in GMT+1 timezone
		"h_fin": "10h00", // ending time
		"h_type": "Presentation", // for sorting purpose, you just have to be consistent with your choice
		"categorie": "Pres" // for sorting purpose, same
	}, {
		"h_date": "Vendredi 21 Juillet 2023", // another example
		"amphi": "",
		"intitule": "SSES - 2ème session",
		"ens": "",
		"h_debut": "9h00",
		"h_fin": "17h00",
		"h_type": "CM",
		"categorie": "SSES"
	}]
}

Side note: Utilities to generate the data file exist but are not included in this repository.

Launch

Back-end:

You must have the following env variables set :

  DATABASE_URL=postgres://__login__:___password___@___server___:__port__/__path__ # see above
  SENDGRID_API_KEY # see above
  FLASK_ENV=production # if production, else set to debug, and add a DEUBG=True variable
  SECRET_API_KEY # must be a secret generated string, is used for token & password hashes generation

Then:

python ./run.py

Front-end

  • for debug: 
    npm run serve
  • for release: 
    npm run build

Usage

TBD

(back to top)

Roadmap

  • Initial release
  • In the future:
    • TBD

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag “enhancement”. Don’t forget to give the project a star! Thanks again!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

(back to top)

License

Distributed under the AGPLv3 License. See LICENSE.txt for more information.

(back to top)

Contact

Main website

Project Link: https://github.com/guatty/collaborative-slot-scheduler

(back to top)

GitHub

View Github